path: root/doc/faq.txt

Frequently Asked Questions
========================================

What is this thing?
----------------------------------------

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.

.. _devel_vs_stable:

Which release should I use?
----------------------------------------

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.

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.

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 though some are
moving to 1.10.

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. This feature is available in all versions of 1.10 and all later
branches.

The self-test program can't locate the library
-----------------------------------------------

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 ``LD_LIBRARY_PATH``
variable. You can add the currently directory to the list of
directories to search with this Bourne shell command::

  $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:.

If you install the library into a well known location like
``/usr/local/lib``, then probably no particular
``LD_LIBRARY_PATH`` needs to be set.

My program aborts with any message
----------------------------------------

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.

Is the library thread-safe?
----------------------------------------

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
``Botan::LibraryInitializer`` 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.

How do I load this key generated by OpenSSL into botan?
--------------------------------------------------------

The encrypted key format used by the ``openssl`` command line tool is
undocumented and apparently specific to OpenSSL. The easiest approach
is to convert it to the (standard) PKCS #8 format, using::

  openssl pkcs8 -topk8 -in my_key.pem

Add ``-nocrypt`` 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.

For unencrypted keys, you can also manually decode the parameters
using the existing PEM and BER support; see :botan-devel:`this post
<2010-June/001156>` to the dev list for an example.

Is botan FIPS 140 certified?
----------------------------------------

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.

Is this thing safe to use?
----------------------------------------

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
*impartial* 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).

There has been one known security flaw. Between versions 0.7.8
(released Feb 2002) and 1.3.7 (released Dec 2003), the ``es_unix``
module, which runs Unix programs to gather entropy for seeding a
random number generator, ran programs by invoking the ``popen``
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 ``/usr/bin``; the list of directories to search
can be controlled by the application.

Is botan vulnerable to timing attacks?
----------------------------------------

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.

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.

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.

I think I've found a security flaw. What should I do?
------------------------------------------------------------

You can do any combination of:

* Contact the current lead maintainer personally; currently
  `Jack Lloyd <http://www.randombit.net>`_
  (`personal PGP key <http://www.randombit.net/keys/pgpkey.html>`_)

* Email the `development list
  <http://lists.randombit.net/mailman/listinfo/botan-devel>`_

* File a bug in `Bugzilla <http://bugs.randombit.net/>`_

Does botan support SSL/TLS, SSH, S/MIME, OpenPGP...
------------------------------------------------------------

Support for SSL/TLS is included in version 1.9.4 and later. Currently
SSLv3 and TLS 1.0 and 1.1 are supported. The latest development
versions also support TLS 1.2.

`NetSieben SSH <http://netsieben.com/products/ssh/>`_ is an open
source SSHv2 implementation that uses botan.

A preliminary and very incomplete implementation of CMS (the crypto
layer underlying S/MIME) is included in ``src/cms``, but it needs a
lot of love and attention before being truly useful.

There is currently no support for OpenPGP.

Will it work on my platform XYZ??
----------------------------------------

The most common stumbling block is a compiler that is buggy or can't
handle modern C++ (specifically, C++98). Check out the :doc:`build log
<build_log>` for a sense of which platforms are actively being tested.

Versions 1.11.0 and higher require a C++11 compiler. GCC 4.7.0 and
Clang 3.1 are known to work well.

I'm not feeling this, what can I use instead?
------------------------------------------------------------

* `Crypto++ <http://www.cryptopp.com/>`_ 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++.

* `OpenSSL <http://www.openssl.org>`_ 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.

* `Adam Shostack <http://www.homeport.org/~adam/crypto/>`_ maintains a
  (somewhat out of date) list of open source crypto libraries.