Update docs

7 files changed, 318 insertions, 37 deletions

diff --git a/doc/algos.txt b/doc/algos.txt
index 0221405d6..bf2a91b0c 100644
--- a/doc/algos.txt
+++ b/doc/algos.txt
@@ -1,11 +1,84 @@
 Algorithms
-=================================
+========================================
+
+Supported Algorithms
+----------------------------------------
+
+Botan provides a number of different cryptographic algorithms and
+primitives, including:
+
+* Public key cryptography
+
+  * Encryption algorithms RSA, ElGamal, DLIES (padding schemes OAEP,
+    PKCS #1 v1.5)
+
+  * Signature algorithms RSA, DSA, ECDSA, GOST 34.10-2001,
+    Nyberg-Rueppel, Rabin-Williams (padding schemes PSS, PKCS #1 v1.5,
+    X9.31)
+
+  * Key agreement techniques Diffie-Hellman and ECDH
+
+* Hash functions
+
+  * NIST hashes: SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512
+
+  * RIPE hashes: RIPEMD-160 and RIPEMD-128
+
+  * SHA-3 candidates Skein-512, Keccak, and Blue Midnight Wish-512
+
+  * Other common hash functions Whirlpool and Tiger
+
+  * National standard hashes HAS-160 and GOST 34.11
+
+  * Obsolete or insecure hashes MD5, MD4, MD2
+
+  * Non-cryptographic checksums Adler32, CRC24, CRC32
+
+* Block ciphers
+
+    * AES (Rijndael) and AES candidates Serpent, Twofish, MARS, CAST-256, RC6
+
+    * DES, and variants 3DES and DESX
+
+    * National/telecom block ciphers SEED, KASUMI, MISTY1, GOST 28147, Skipjack
+
+    * Other block ciphers including Blowfish, CAST-128, IDEA, Noekeon,
+      TEA, XTEA, RC2, RC5, SAFER-SK, and Square
+
+    * Block cipher constructions Luby-Rackoff and Lion
+
+    * Block cipher modes ECB, CBC, CBC/CTS, CFB, OFB, CTR, XTS and
+      authenticated cipher mode EAX
+
+* Stream ciphers ARC4, Salsa20/XSalsa20, Turing, and WiderWake4+1
+
+* Authentication codes HMAC, CMAC (aka OMAC1), CBC-MAC, ANSI X9.19
+  DES-MAC, and the protocol-specific SSLv3 authentication code
+
+* Public Key Infrastructure
+
+    * X.509 certificates (including generating new self-signed and CA
+      certs) and CRLs
+
+    * Certificate path validation
+
+    * PKCS #10 certificate requests (creation and certificate issue)
+
+* Other cryptographic utility functions including
+
+    * Key derivation functions for passwords: PBKDF1 (PKCS #5 v1.5),
+      PBKDF2 (PKCS #5 v2.0), OpenPGP S2K (RFC 2440)
+
+    * General key derivation functions KDF1 and KDF2 from IEEE 1363
+
+    * PRFs from ANSI X9.42, SSL v3.0, TLS v1.0
+
 
 Recommended Algorithms
 ---------------------------------
 
 This section is by no means the last word on selecting which
-algorithms to use.  However, Botan includes a sometimes bewildering
+algorithms to use.  However, botan includes a sometimes bewildering
 array of possible algorithms, and unless you're familiar with the
 latest developments in the field, it can be hard to know what is
 secure and what is not. The following attributes of the algorithms
@@ -14,25 +87,25 @@ patent status, support by other implementations, and efficiency (in
 roughly that order).
 
 It is intended as a set of simple guidelines for developers, and
-nothing more.  It's entirely possible that there are algorithms in
-Botan that will turn out to be more secure than the ones listed, but
-the algorithms listed here are (currently) thought to be safe.
+nothing more.  It's entirely possible that there are algorithms that
+will turn out to be more secure than the ones listed, but the
+algorithms listed here are (currently) thought to be safe.
 
- - Block ciphers: AES or Serpent in CBC, CTR, or XTS mode
+* Block ciphers: AES or Serpent in CBC, CTR, or XTS mode
 
- - Hash functions: SHA-256, SHA-512
+* Hash functions: SHA-256, SHA-512
 
- - MACs: HMAC with any recommended hash function
+* MACs: HMAC with any recommended hash function
 
- - Public Key Encryption: RSA with "EME1(SHA-256)"
+* Public Key Encryption: RSA with "EME1(SHA-256)"
 
- - Public Key Signatures: RSA with EMSA4 and any recommended
-    hash, or DSA or ECDSA with "EMSA1(SHA-256)"
+* Public Key Signatures: RSA with EMSA4 and any recommended hash, or
+  DSA or ECDSA with "EMSA1(SHA-256)"
 
- - Key Agreement: Diffie-Hellman or ECDH, with "KDF2(SHA-256)"
+* Key Agreement: Diffie-Hellman or ECDH, with "KDF2(SHA-256)"
 
 Algorithms Listing
----------------------------------
+----------------------------------------
 
 Botan includes a very sizable number of cryptographic algorithms. In
 nearly all cases, you never need to know the header file or type name
@@ -42,9 +115,8 @@ by SCAN (Standard Cryptographic Algorithm Naming), which is a document
 that specifies how strings are mapped onto algorithm objects, which is
 useful for a wide variety of crypto APIs (SCAN is oriented towards
 Java, but Botan and several other non-Java libraries also make at
-least some use of it). For full details, read the SCAN document, which
-can be found at
-http://www.users.zetnet.co.uk/hopwood/crypto/scan/
+least some use of it). For full details, read the `SCAN document
+<http://www.users.zetnet.co.uk/hopwood/crypto/scan/>`_.
 
 Many of these algorithms can take options (such as the number of
 rounds in a block cipher, the output size of a hash function,
diff --git a/doc/conf.py b/doc/conf.py
index f1c6ebee4..e0600da81 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -56,12 +56,11 @@ copyright = u'2000-2011, Jack Lloyd'
 # built documents.
 #
 # The short X.Y version.
-version = '%d.%d' % (botan_version.major, botan_version.minor)
+version = '%d.%d' % (botan_version.release_major, botan_version.release_minor)
 # The full version, including alpha/beta/rc tags.
-release = '%d.%d.%d%s' % (botan_version.major,
-                          botan_version.minor,
-                          botan_version.patch,
-                          botan_version.release_suffix)
+release = '%d.%d.%d' % (botan_version.release_major,
+                        botan_version.release_minor,
+                        botan_version.release_patch)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/contrib.txt b/doc/contrib.txt
index fb30fbad4..2ad420747 100644
--- a/doc/contrib.txt
+++ b/doc/contrib.txt
@@ -1,7 +1,11 @@
 
-Contributing To Botan
+Contributing
 ========================================
 
+Contributions to the library are most certainly welcome. To increase
+the chances your patch will actually make it into releases in a timely
+fashion, here are some guidelines for patch submission.
+
 Getting The Latest Sources
 ----------------------------------------
 
@@ -58,3 +62,10 @@ After you finish your changes, you can review them using ``mtn diff``
 to diff against the latest official head; send the output to the
 mailing list for review and inclusion.
 
+Don't forget to update the file ``credits.txt`` with your information,
+if you want to be listed as a contributor. Also, if your patch is
+substantial enough to be considered copyrightable, add yourself to
+``license.txt``.
+
+Patches are best directed to the `botan-devel
+<http://lists.randombit.net/mailman/listinfo/botan-devel>`_.
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.
diff --git a/doc/index.txt b/doc/index.txt
index f286ee471..33f53db79 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -20,6 +20,7 @@ Contents:
    bigint
    examples
    algos
+   faq
    pgpkeys
    license
    credits
diff --git a/doc/log.txt b/doc/log.txt
index 5feeaeece..44da4d430 100644
--- a/doc/log.txt
+++ b/doc/log.txt
@@ -5,7 +5,7 @@ Release Notes
 2011
 ----------------------------------------
 
-Version 1.9.16, Not Yet Released
+Version 1.9.16, 2011-04-11
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
   * Second release candidate for 1.10.0
diff --git a/doc/users.txt b/doc/users.txt
index a855ca56e..9c7d274d3 100644
--- a/doc/users.txt
+++ b/doc/users.txt
@@ -96,7 +96,7 @@ Commercial Software
 * `E.V.E. Paradox <http://www.eveparadox.com>`_, a suite of games for
   Windows, uses botan.
 
-Books, Dissertations, Journal Papers
+Research Projects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * `A Unified Approach to Intra-Domain Security
@@ -114,17 +114,12 @@ Books, Dissertations, Journal Papers
   Protected IPv6 Networks Through Secret-key Sharing
   <http://www.stormingmedia.us/01/0151/A015134.pdf>`_
 
-  * `An experimental tamper detection system
-    <http://www.cis.udel.edu/~hiper/passages/papers/jochenMILCOM03.pdf>`_
-    designed by researchers from the University of Delaware and the US
-    Army Research Laboratory.
-
-  * A prototype implementation of a telephony signal security system,
-    described in `Prototyping and evaluation of TCAPsec
-    <http://www.cs.kau.se/cs/education/courses/davddiss/Uppsatser_2007/D2007-04.pdf>`_
-    by Kang Chung and Mathilda Gustafsson.
-
-  * `Code Reading: An Open Source Perspective
-    <http://www.spinellis.gr/codereading/>`_, by Diomidis Spinnellis,
-    includes code from an early version of botan (then called OpenCL).
+* `An experimental tamper detection system
+  <http://www.cis.udel.edu/~hiper/passages/papers/jochenMILCOM03.pdf>`_
+  designed by researchers from the University of Delaware and the US
+  Army Research Laboratory.
 
+* A prototype implementation of a telephony signal security system,
+  described in `Prototyping and evaluation of TCAPsec
+  <http://www.cs.kau.se/cs/education/courses/davddiss/Uppsatser_2007/D2007-04.pdf>`_
+  by Kang Chung and Mathilda Gustafsson.