Botan

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.

Who wrote it?

It was started as a personal project by Jack Lloyd,who continues to be the maintainer and release manager. Since the first release in 2001, a number of individuals and organizations have contributed.

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.

Why do I get a SyntaxError when I run configure.py?

The configure.py script in 1.10 and later versions requires Python 2.6 or higher. In Python 3 the exception catching syntax changed, and while 2.6 and 2.7 understand both syntaxes, 2.5 does not. If you see an error like this:

File "./configure.py", line 62
  except OSError as e:
                 ^
SyntaxError: invalid syntax

Then you are using Python 2.5 (or earlier). For Python 2.5, a Perl one liner can fix the syntax:

perl -pi -e "s/except (.*) as (.*):/except $1, $2:/g" configure.py

or in Python:

import re

lines = re.sub(r"except (.*) as (.*):", r"except \1, \2:",
               "".join(open("configure.py").readlines()))
open("configure.py", "w").write(lines)

However Python 2.4 is missing a number of features and cannot be used to configure the build in 1.10; you’ll need to upgrade to at least 2.5 (or preferably 2.7 or 3.1).

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.

In 1.11.0 and later, the C++11 std thread library is used and the library always serializes access.

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 this post 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:

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

The latest development (1.11) releases support TLS up to TLS v1.2. The 1.10 releases support up to TLS v1.1 using a different design and API; new applications intending to use TLS should use 1.11.

NetSieben SSH is an open source SSHv2 client implementation that uses botan.

There is currently no support for OpenPGP, CMS, OTR, or SSHv2 servers.

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). Most any recent release of GCC, Clang, Intel C++, Visual C++, etc are all fine. It is tested most heavily on Linux but especially the stable versions are built and tested across a range of Unices as well as OS X and Windows.

Versions 1.11.0 and higher require a C++11 compiler as well as Boost filesystem (plus optional use of Boost asio). GCC 4.7.0 and Clang 3.1 or higher should work. Visual C++ 2013 seems to support all the required features, but probably needs a bit of work, as Windows has not seen much attention.

I’m not feeling this, what can I use instead?

  • NaCl (and portable derivatives such as libsodium) provide a small selection of algorithms for ECC key exchange (Curve25519) and message encryption and authentication (XSalsa20+Poly1305) carefully implemented for performance and side channel security. It is an excellent choice if you do not need compatability with any other software.
  • OpenSSL 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. BSD plus wonky advertising clause.
  • Crypto++ is a C++ crypto library which is roughly feature comparable to botan but with a very different approach to the API. Boost license.