mirror of
https://github.com/moparisthebest/mailiverse
synced 2024-12-11 00:32:15 -05:00
209 lines
9.0 KiB
Plaintext
209 lines
9.0 KiB
Plaintext
|
|
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
|
|
<http://lists.randombit.net/pipermail/botan-devel/2010-June/001156.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 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/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 version 1.9.4 and later. 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 ``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
|
|
<build_log>` 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.
|