diff options
Diffstat (limited to 'doc/faq.txt')
| -rw-r--r-- | doc/faq.txt | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/doc/faq.txt b/doc/faq.txt new file mode 100644 index 000000000..fe1014e82 --- /dev/null +++ b/doc/faq.txt @@ -0,0 +1,203 @@ + +Frequantly 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. + +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 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. + +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 +<http://lists.randombit.net/pipermail/botan-devel/2010-June/001157.html>`_ +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 suble, 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/pgpgkey.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 the most recent development +releases (1.9.x). Currently SSLv3 and TLS 1.0 and 1.1 are supported. + +`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 <tt>src/cms</tt>, 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 `build list +<http://botan.randombit.net/builds.html>`_ for a sense of which +platforms are actively being tested. + +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. + +* `XySSL <http://www.ohloh.net/projects/xyssl>`_ is a C library + providing a very small footprint crypto library and SSL + implementation. + +* `Adam Shostack <http://www.homeport.org/~adam/crypto/>`_ maintains a + (somewhat out of date) list of open source crypto libraries. |