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. 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. 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 `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: * Contact the current lead maintainer personally; currently `Jack Lloyd `_ (`personal PGP key `_) * Email the `development list `_ * File a bug in `Bugzilla `_ 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 `_ 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 ` 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++ `_ 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 `_ 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 `_ maintains a (somewhat out of date) list of open source crypto libraries.