distrib > Mageia > cauldron > i586 > by-pkgid > 92a9f9a2ff17105809ab69f8e09db031 > files > 66


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

<html xmlns="">
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Frequently Asked Questions &#8212; 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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>
    <script type="text/javascript" src="_static/language_data.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Known Users" href="users.html" />
    <link rel="prev" title="Credits" href="credits.html" /> 
    <div class="header-wrapper">
      <div class="header">

    <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 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 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 notranslate"><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 notranslate"><div class="highlight"><pre><span></span>$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:.
<p>If you install the library into a well known location like
<code class="docutils literal notranslate"><span class="pre">/usr/local/lib</span></code>, then probably no particular
<code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code> needs to be set.</p>
<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 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 notranslate"><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 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 notranslate"><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 notranslate"><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>
<p>Add <code class="docutils literal notranslate"><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="">this post</a>
to the dev list for an example.</p>
<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 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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">/usr/bin</span></code>; the list of directories to search
can be controlled by the application.</p>
<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
<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
<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="">Jack Lloyd</a>
(<a class="reference external" href="">personal PGP key</a>)</li>
<li>Email the <a class="reference external" href="">development list</a></li>
<li>File a bug in <a class="reference external" href="">Bugzilla</a></li>
<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="">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 notranslate"><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 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 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="">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="">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="">XySSL</a> is a C library
providing a very small footprint crypto library and SSL
<li><a class="reference external" href="">Adam Shostack</a> maintains a
(somewhat out of date) list of open source crypto libraries.</li>

        <div class="sidebar">
          <h3>Table of Contents</h3>
<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>

          <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" />
        <div class="clearer"></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"
          <div role="note" aria-label="source link">
              <a href="_sources/faq.txt"
                rel="nofollow">Show Source</a>

        <div class="right">
    <div class="footer" role="contentinfo">
        &#169; Copyright 2000-2011, Jack Lloyd.
      Created using <a href="">Sphinx</a> 1.8.3.
        <div class="clearer"></div>