Botan FAQ

What is it?

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 Botan also supports a number of standards and de-facto standards.

How is support for OpenPGP, SSH, S/MIME, SSL/TLS...

NetSieben SSH is an open source SSH implementation built on top of Botan.

Ajisai is an implementation of SSLv3 and TLS v1.0 which uses Botan for cryptography and certificate handling.

A preliminary and very incomplete implementation of CMS (the crypto layer underlying S/MIME) is included in Botan.

What does this have to do with OpenCL?

The early releases of Botan were named OpenCL. The project was renamed Botan in 2002. It has nothing to do with Apple's OpenCL, and the name was changed long before Apple's project was announced.

How portable is Botan?

The most common stumbling block is a compiler that is buggy or can't handle modern C++ (specifically, C++98). See this list of recent build results for a sense of which platforms are actively being tested.

Are hardware accelerators supported?

Botan can use essentially arbitrary backends for cryptographic operations. It has been tested with both hardware and software based backends, but there are only limited numbers of each, due primarily to lack of access to further hardware cards (as well as the associated drivers/SDKs).

Prior to Botan 1.7.6, crypto accelerators made by AEP Systems (the "AEP Sureware Runner" line - AEP1000 and AEP2000) were supported, however this was dropped due to the inability to test. Open source drivers for this card do exist, but they need to be ported to more modern systems; the currently extant version of the drivers is for Linux 2.4, and does not seem to be 64-bit or SMP safe. So currently only GNU MP 4 and OpenSSL BN software backends are supported as alternatives to Botan's native BigInt package.

Generally speaking, adding support for a new engine is not difficult (it typically takes a few hundred lines of code), as long as the appropriate hardware, software, and documentation are made available. Ideally these could be donated (making it possible to continue to test and enhance the module over time), but a loan or remote access could be useful too. If you have an interest in getting your crypto accelerator supported by Botan, please send a mail to the developer list.

My program aborts on startup!

Does your main function wrap all code inside a try/catch block? If an exception is thrown and is not caught, many runtimes simply crash the process without providing any sort of diagnostic.

My program fails with a Botan initialization error

You must create a Botan::LibraryInitializer object in order for anything in Botan to work. This is not actually entirely true, but it's a useful first order approximation (and is almost certainly the problem if you observe a Botan exception about initialization problems). See the API documentation for details.

My threaded application crashes. Is Botan 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. If for whatever reason a working mutex implementation cannot be found, LibraryInitializer will throw an exception rather than continue operating in a bad state.

Compilation fails in x509stat.cpp using Visual Studio 2003

There is a bug in the compiler with regards to classes defined within functions. A post to the devel mailing list contains a patch that fixes the problem. Visual Studio 2005 does not have this bug.

On Windows, I get strange paths in the Makefile

There is a bug in the configuration script in some versions that causes the script to get confused. You can workaround this problem by invoking the script as "perl ./configure.pl" (note the leading ./)

On Unix, I get errors that the library cannot be found when I try to run the self-test application

Are you sure either the current working directory ('.') or the directory Botan is building into are in the dynamic library path? On some systems this is controlled by the LD_LIBRARY_PATH variable. You can add the currently directory to the list of directories to search with the 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.

Is Botan safe to use?

The primary author/maintainer of Botan (Jack Lloyd) has several years of experience performing application code review for security flaws, and has performed several FIPS 140 validations of hardware and software crypto implementations. However Botan 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 funding/shepherding such a review of the Botan source, please contact the maintainers).

There has been one known security flaw. Between versions 0.7.8 (Feb 2002) and 1.3.7 (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 mean setuid or setgid programs that used Botan 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.

Does Botan defend against side-channel attacks?

Botan does not make any particular effort to defend against side-channel attacks such as differential power analysis or techniques that derive data based on cache eviction rates. These attacks are difficult if not impossible to defend against, and typically the countermeasures that are known rely on hardware-specific assumptions.

Algorithm implementations that do defend against side-channel attacks could be introduced via an engine module. That would allow the side-channel protections to apply to all users without requiring any direct library code changes.

Does Botan defend against timing attacks? What about fault injection 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. The ECDSA/ECDH implementation using some algorithms which are resistant to timing attacks which were implemented by FlexSecure GmbH as part of their InSiTo library. At this time it is not certain if Botan has correctly merged all the required code such that Botan's implementation is similarly resistant to timing attacks.

Public key algorithms implemented using the Chinese Remainder Theorem (in Botan, 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. That is why Botan checks the results of RSA and RW private key operations for consistency with the public key - if the results are not consistent, then Botan signals that an error has occurred rather than release information that might compromise the key.

Joseph Bonneau and Ilya Mironov's paper Cache-Collision Timing Attacks Against AES describes an attack that can recover AES keys with as few as 213 samples. To quote from their results:

The attacks in this paper are widely applicable as many AES implementations have made no significant changes to the original optimized Rijndael code. In addition to OpenSSL v. 0.9.8.(a), which was used in our experiments, the AES implementations of Crypto++ 5.2.1 and LibTomCrypt 1.09 use the original Rijndael C implementation with very few changes and are highly vulnerable. The AES implementations in libgcrypt v. 1.2.2 and Botan v. 1.4.2 are also vulnerable, but use a smaller byte-wide final table which lessens the effectiveness of the attacks.

Botan's implementation of AES continues to use a byte-wide sbox table for the final round. That said, due to the design of AES it is likely that any fast software implementation will remain quite vulnerable to timing attacks. If this is a concern, another block cipher, such as Serpent, should be used instead.

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

You can do any combination of:

What can I use instead of Botan?