<!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>Frequently Asked Questions — 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="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="top" title="Botan" href="contents.html" /> <link rel="next" title="Known Users" href="users.html" /> <link rel="prev" title="Credits" href="credits.html" /> </head> <body role="document"> <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" role="main"> <div class="section" id="frequently-asked-questions"> <h1>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h1> <div class="section" id="what-is-this-thing"> <h2>What is this thing?<a class="headerlink" href="#what-is-this-thing" title="Permalink to this headline">¶</a></h2> <p>Botan is a library written in C++ which provides a fairly high level and C++-ish interface to a number of different crypto algorithms. In addition to the bare algorithms there is also support for number of standards and de-facto standards like X.509v3 certificates, and various useful constructs like format-preserving encryption, all or nothing transforms, and secret splitting.</p> </div> <div class="section" id="which-release-should-i-use"> <span id="devel-vs-stable"></span><h2>Which release should I use?<a class="headerlink" href="#which-release-should-i-use" title="Permalink to this headline">¶</a></h2> <p>The library is normally released along two different trees, termed stable and development. The stable tree is a branch off the main line, and typically only sees bug fixes; almost all new development occurs in the unstable/development releases. The primary issue is not stability of the program (bugs of course do occur, and are more likely to occur in code that is more in flux), but rather stability of API and ABI. In particular, you should not expect any level of ABI stability between releases on the development branch, and API changes may be made without notice. Feel free to send comments on API changes, or API problems, to the list.</p> <p>If you don’t want to have to worry about tracking a moving target, and just want something that works, you’ll probably prefer using the stable releases. If you want to get the latest features, the development releases are the obvious choice.</p> <p>If you want to ship a binary that is usable out of the box on a Linux distro that ships botan, you’ll probably want to match versions with that distro; as of this writing most ship with 1.8.</p> <p>If you’re building an application that will embed botan into it (without relying on a shared library), you want to use an amalgamation build, which basically turns botan into a single header and a single source file which you can easily include in your existing application build. In this case you can pick which ever tree you prefer.</p> </div> <div class="section" id="the-self-test-program-can-t-locate-the-library"> <h2>The self-test program can’t locate the library<a class="headerlink" href="#the-self-test-program-can-t-locate-the-library" title="Permalink to this headline">¶</a></h2> <p>Are you sure either the current working directory (‘.’) or the directory botan is building into are in the dynamic library path? On many Unix systems this is controlled by the <code class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></code> variable. You can add the currently directory to the list of directories to search with this Bourne shell command:</p> <div class="highlight-cpp"><div class="highlight"><pre><span></span>$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:. </pre></div> </div> <p>If you install the library into a well known location like <code class="docutils literal"><span class="pre">/usr/local/lib</span></code>, then probably no particular <code class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></code> needs to be set.</p> </div> <div class="section" id="my-program-aborts-with-any-message"> <h2>My program aborts with any message<a class="headerlink" href="#my-program-aborts-with-any-message" title="Permalink to this headline">¶</a></h2> <p>Does your main function wrap all code inside a try/catch block? If an exception is thrown and is not caught, many C++ runtimes simply crash the process without providing any sort of diagnostic.</p> </div> <div class="section" id="is-the-library-thread-safe"> <h2>Is the library thread-safe?<a class="headerlink" href="#is-the-library-thread-safe" title="Permalink to this headline">¶</a></h2> <p>Yes, botan is thread safe. However, because mutual exclusion depends on OS specific code, you must load a module to help. POSIX threads and Win32 critical sections are both supported out of the box, other thread libraries are very easy to add. To enable thread safe operation, include “thread_safe” in the string you pass to <code class="docutils literal"><span class="pre">Botan::LibraryInitializer</span></code> constructor. If for whatever reason a working mutex implementation cannot be found, LibraryInitializer will throw an exception rather than continue operating in a bad state.</p> </div> <div class="section" id="how-do-i-load-this-key-generated-by-openssl-into-botan"> <h2>How do I load this key generated by OpenSSL into botan?<a class="headerlink" href="#how-do-i-load-this-key-generated-by-openssl-into-botan" title="Permalink to this headline">¶</a></h2> <p>The encrypted key format used by the <code class="docutils literal"><span class="pre">openssl</span></code> command line tool is undocumented and apparently specific to OpenSSL. The easiest approach is to convert it to the (standard) PKCS #8 format, using:</p> <div class="highlight-cpp"><div class="highlight"><pre><span></span><span class="n">openssl</span> <span class="n">pkcs8</span> <span class="o">-</span><span class="n">topk8</span> <span class="o">-</span><span class="n">in</span> <span class="n">my_key</span><span class="p">.</span><span class="n">pem</span> </pre></div> </div> <p>Add <code class="docutils literal"><span class="pre">-nocrypt</span></code> to the command line if you want the resulting PKCS #8 file to be unencrypted, otherwise it will ask you for a new password to use.</p> <p>For unencrypted keys, you can also manually decode the parameters using the existing PEM and BER support; see <a class="reference external" href="http://lists.randombit.net/pipermail/botan-devel/2010-June/001156.html">this post</a> to the dev list for an example.</p> </div> <div class="section" id="is-botan-fips-140-certified"> <h2>Is botan FIPS 140 certified?<a class="headerlink" href="#is-botan-fips-140-certified" title="Permalink to this headline">¶</a></h2> <p>No version of botan has been certified under FIPS 140. This is unlikely to happen unless/until an organization is willing to fund and shepherd the validation process, which typically requires several months and many thousands of dollars.</p> </div> <div class="section" id="is-this-thing-safe-to-use"> <h2>Is this thing safe to use?<a class="headerlink" href="#is-this-thing-safe-to-use" title="Permalink to this headline">¶</a></h2> <p>The primary author/maintainer (Jack Lloyd) has 5+ years of experience reviewing code for security flaws, and has additionally performed several FIPS 140 validations of hardware and software crypto implementations. However the library has never undergone an <em>impartial</em> third-party security review, and thus it is entirely possible/probable that a number of exploitable flaws remain in the source. (If your company is interested in handling such a review, please contact the maintainers).</p> <p>There has been one known security flaw. Between versions 0.7.8 (released Feb 2002) and 1.3.7 (released Dec 2003), the <code class="docutils literal"><span class="pre">es_unix</span></code> module, which runs Unix programs to gather entropy for seeding a random number generator, ran programs by invoking the <code class="docutils literal"><span class="pre">popen</span></code> library function with commands with no leading directory names. This means setuid or setgid programs that used this entropy source could be tricked into executing arbitrary programs via manipulation of the PATH variable. Later versions will only search through specific (presumed safe) directories like <code class="docutils literal"><span class="pre">/usr/bin</span></code>; the list of directories to search can be controlled by the application.</p> </div> <div class="section" id="is-botan-vulnerable-to-timing-attacks"> <h2>Is botan vulnerable to timing attacks?<a class="headerlink" href="#is-botan-vulnerable-to-timing-attacks" title="Permalink to this headline">¶</a></h2> <p>Botan’s public key implementations do make some attempt to defend against timing attacks; random blinding is used to protect all RSA, Rabin-Williams, ElGamal, and Diffie-Hellman private key operations.</p> <p>Public key algorithms implemented using the Chinese Remainder Theorem (RSA and Rabin-Williams) are subject to a catastrophic failure: if a computational error (either induced by an attacker or merely accidental) occurs during the private key operation, the private key can be revealed. Other, more subtle, fault attacks are possible against other schemes. For this reason, private key operations are checked for consistency with the public key - if the results are not consistent, then an exception is thrown indicating an error has occurred rather than release information that might compromise the key.</p> <p>AES implementations are usually quite vulnerable to timing attacks. The table based implementation of AES included in botan uses small tables in the first and last rounds which makes such attacks somewhat more difficult. Alternate implementations of AES using SSSE3 and AES-NI instruction sets are also included, and run in constant time, but of course require a processor that supports these instruction sets.</p> </div> <div class="section" id="i-think-i-ve-found-a-security-flaw-what-should-i-do"> <h2>I think I’ve found a security flaw. What should I do?<a class="headerlink" href="#i-think-i-ve-found-a-security-flaw-what-should-i-do" title="Permalink to this headline">¶</a></h2> <p>You can do any combination of:</p> <ul class="simple"> <li>Contact the current lead maintainer personally; currently <a class="reference external" href="http://www.randombit.net">Jack Lloyd</a> (<a class="reference external" href="http://www.randombit.net/pgpgkey.html">personal PGP key</a>)</li> <li>Email the <a class="reference external" href="http://lists.randombit.net/mailman/listinfo/botan-devel">development list</a></li> <li>File a bug in <a class="reference external" href="http://bugs.randombit.net/">Bugzilla</a></li> </ul> </div> <div class="section" id="does-botan-support-ssl-tls-ssh-s-mime-openpgp"> <h2>Does botan support SSL/TLS, SSH, S/MIME, OpenPGP...<a class="headerlink" href="#does-botan-support-ssl-tls-ssh-s-mime-openpgp" title="Permalink to this headline">¶</a></h2> <p>Support for SSL/TLS is included in version 1.9.4 and later. Currently SSLv3 and TLS 1.0 and 1.1 are supported.</p> <p><a class="reference external" href="http://netsieben.com/products/ssh/">NetSieben SSH</a> is an open source SSHv2 implementation that uses botan.</p> <p>A preliminary and very incomplete implementation of CMS (the crypto layer underlying S/MIME) is included in <code class="docutils literal"><span class="pre">src/cms</span></code>, but it needs a lot of love and attention before being truly useful.</p> <p>There is currently no support for OpenPGP.</p> </div> <div class="section" id="will-it-work-on-my-platform-xyz"> <h2>Will it work on my platform XYZ??<a class="headerlink" href="#will-it-work-on-my-platform-xyz" title="Permalink to this headline">¶</a></h2> <p>The most common stumbling block is a compiler that is buggy or can’t handle modern C++ (specifically, C++98). Check out the <a class="reference internal" href="build_log.html"><span class="doc">build log</span></a> for a sense of which platforms are actively being tested.</p> </div> <div class="section" id="i-m-not-feeling-this-what-can-i-use-instead"> <h2>I’m not feeling this, what can I use instead?<a class="headerlink" href="#i-m-not-feeling-this-what-can-i-use-instead" title="Permalink to this headline">¶</a></h2> <ul class="simple"> <li><a class="reference external" href="http://www.cryptopp.com/">Crypto++</a> is another C++ crypto library. Its API is more heavily based on templates and in general has a very different design philosophy from botan - so if you feel botan’s API is not a good match, you may well like Crypto++.</li> <li><a class="reference external" href="http://www.openssl.org">OpenSSL</a> is written in C and mostly targeted to being an SSL/TLS implementation but there is a lot of other stuff in there as well.</li> <li><a class="reference external" href="http://www.ohloh.net/projects/xyssl">XySSL</a> is a C library providing a very small footprint crypto library and SSL implementation.</li> <li><a class="reference external" href="http://www.homeport.org/~adam/crypto/">Adam Shostack</a> maintains a (somewhat out of date) list of open source crypto libraries.</li> </ul> </div> </div> </div> </div> </div> </div> <div class="sidebar"> <h3>Table Of Contents</h3> <ul> <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"><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> <div role="search"> <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> </div> </div> <div class="clearer"></div> </div> </div> <div class="footer-wrapper"> <div class="footer"> <div class="left"> <div role="navigation" aria-label="related navigaton"> <a href="credits.html" title="Credits" accesskey="P">previous</a> | <a href="users.html" title="Known Users" accesskey="N">next</a> | <a href="genindex.html" title="General Index" accesskey="I">index</a> </div> <div role="note" aria-label="source link"> <br/> <a href="_sources/faq.txt" rel="nofollow">Show Source</a> </div> </div> <div class="right"> <div class="footer" role="contentinfo"> © Copyright 2000-2011, Jack Lloyd. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9. </div> </div> <div class="clearer"></div> </div> </div> </body> </html>