diff options
Diffstat (limited to 'doc/website/faq.rst')
| -rw-r--r-- | doc/website/faq.rst | 255 |
1 files changed, 0 insertions, 255 deletions
diff --git a/doc/website/faq.rst b/doc/website/faq.rst deleted file mode 100644 index b59595521..000000000 --- a/doc/website/faq.rst +++ /dev/null @@ -1,255 +0,0 @@ - -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 -<http://www.randombit.net>`_,who continues to be the maintainer and -release manager. Since the first release in 2001, a number of -individuals and organizations have :doc:`contributed <credits>`. - -.. _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 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 :botan-devel:`this post -<2010-June/001156>` 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 <http://www.randombit.net>`_ - (`personal PGP key <http://www.randombit.net/keys/pgpkey.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... ------------------------------------------------------------- - -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 <http://netsieben.com/products/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 <http://nacl.cr.yp.to/>`_ (and portable derivatives such as - `libsodium <https://github.com/jedisct1/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 <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. BSD plus wonky advertising clause. - -* `Crypto++ <http://www.cryptopp.com/>`_ is a C++ crypto library which - is roughly feature comparable to botan but with a very different - approach to the API. Boost license. |