Last modified: 2010/06/11
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.
The library is normally released along two different trees, called stable and development. The stable tree is a branch off the main line, which 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 no release is ever shipped with known bugs), but rather stability of API and ABI. In particular, you should not expect any level of ABI stability between releases on the development branch. Changes to the API are also made, though with a general preference for backwards compatability with code written for older versions.
If you want to ship a binary that is usable out of the box on a Linux distro that ships botan (most do), or you want to ensure you're not having to track a moving target, 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'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 currently only available in the development trees.
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.
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.
You must create a LibraryInitializer object in order
for anything in the library 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 an exception about initialization
problems). See the API documentation for details.
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.
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.
The primary author/maintainer (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 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 funding/shepherding such a review, 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 uses 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.
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.
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. That is why the results of RSA and RW 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 tend to make such attacks more difficult but not impossible. Alternate implementations of AES using SSSE3 and AES-NI instruction sets are also included, and run in constant time.
You can do any combination of:
Support for SSL/TLS is included in the most recent development releases (1.9.x). Currently SSLv3 and TLS 1.0 and 1.1 are supported.
NetSieben 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
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.