More doc updates

12 files changed, 84 insertions, 276 deletions

diff --git a/doc/examples.txt b/doc/examples.txt
index 5d4aad8ed..d58b4fa39 100644
--- a/doc/examples.txt
+++ b/doc/examples.txt
@@ -90,20 +90,3 @@ ASN.1 Parsing
 This example is a simple ASN.1 parser
 
 .. literalinclude:: examples/asn1.cpp
-
-SSL/TLS
-----------------------------------------
-
-SSL Client
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A simple SSL/TLS client
-
-.. literalinclude:: examples/tls_client.cpp
-
-SSL Server
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A simple SSL/TLS server
-
-.. literalinclude:: examples/tls_server.cpp
diff --git a/doc/examples/bcrypt.cpp b/doc/examples/bcrypt.cpp
index 27a98cf33..4154b26ad 100644
--- a/doc/examples/bcrypt.cpp
+++ b/doc/examples/bcrypt.cpp
@@ -1,10 +1,3 @@
-/*
-* Bcrypt example
-* (C) 2011 Jack Lloyd
-*
-* Distributed under the terms of the Botan license
-*/
-
 #include <botan/botan.h>
 #include <botan/bcrypt.h>
 #include <iostream>
diff --git a/doc/examples/tls_client.cpp b/doc/examples/tls_client.cpp
index 9f6f6229a..6c5ad7bde 100644
--- a/doc/examples/tls_client.cpp
+++ b/doc/examples/tls_client.cpp
@@ -1,9 +1,3 @@
-/*
-* (C) 2008 Jack Lloyd
-*
-* Distributed under the terms of the Botan license
-*/
-
 #include <botan/init.h>
 #include <botan/tls_client.h>
 #include "socket.h"
@@ -50,35 +44,30 @@ int main(int argc, char* argv[])
 
       Socket sock(argv[1], port);
 
-      std::auto_ptr<Botan::RandomNumberGenerator> rng(
-         Botan::RandomNumberGenerator::make_rng());
+      AutoSeeded_RNG rng;
 
       Client_TLS_Policy policy;
 
       TLS_Client tls(std::tr1::bind(&Socket::read, std::tr1::ref(sock), _1, _2),
                      std::tr1::bind(&Socket::write, std::tr1::ref(sock), _1, _2),
-                     policy, *rng);
+                     policy, rng);
 
       printf("Handshake extablished...\n");
 
-#if 0
       std::string http_command = "GET / HTTP/1.1\r\n"
                                  "Server: " + host + ':' + to_string(port) + "\r\n\r\n";
-#else
-      std::string http_command = "GET / HTTP/1.0\r\n\r\n";
-#endif
 
       tls.write((const byte*)http_command.c_str(), http_command.length());
 
-      u32bit total_got = 0;
+      size_t total_got = 0;
 
       while(true)
          {
          if(tls.is_closed())
             break;
 
-         byte buf[16+1] = { 0 };
-         u32bit got = tls.read(buf, sizeof(buf)-1);
+         byte buf[128+1] = { 0 };
+         size_t got = tls.read(buf, sizeof(buf)-1);
          printf("%s", buf);
          fflush(0);
 
diff --git a/doc/examples/tls_server.cpp b/doc/examples/tls_server.cpp
index 087ba86fa..be5677c12 100644
--- a/doc/examples/tls_server.cpp
+++ b/doc/examples/tls_server.cpp
@@ -1,9 +1,3 @@
-/*
-* (C) 2008-2010 Jack Lloyd
-*
-* Distributed under the terms of the Botan license
-*/
-
 #include <botan/botan.h>
 #include <botan/tls_server.h>
 
diff --git a/doc/filters.txt b/doc/filters.txt
index b5ce3333b..fa4959699 100644
--- a/doc/filters.txt
+++ b/doc/filters.txt
@@ -202,15 +202,17 @@ Any filters that are attached to the pipe after the fork are
 implicitly attached onto the first branch created by the fork. For
 example, let's say you created this pipe::
 
-  Pipe pipe(new Fork(new Hash_Filter("MD5"), new Hash_Filter("SHA-1")),
+  Pipe pipe(new Fork(new Hash_Filter("SHA-256"),
+                     new Hash_Filter("SHA-512")),
             new Hex_Encoder);
 
 And then called ``start_msg``, inserted some data, then
-``end_msg``. Then ``pipe`` would contain two messages. The
-first one (message number 0) would contain the MD5 sum of the input in
-hex encoded form, and the other would contain the SHA-1 sum of the
-input in raw binary. However, it's much better to use a ``Chain``
-instead.
+``end_msg``. Then ``pipe`` would contain two messages. The first one
+(message number 0) would contain the SHA-256 sum of the input in hex
+encoded form, and the other would contain the SHA-512 sum of the input
+in raw binary. In many situations you'll want to perform a sequence of
+operations on multiple branches of the fork; in which case, use
+``Chain``.
 
 Chain
 ---------------------------------
@@ -228,8 +230,8 @@ from the last section, using chain instead of relying on the implicit
 passthrough the other version used::
 
   Pipe pipe(new Fork(
-                new Chain(new Hash_Filter("MD5"), new Hex_Encoder),
-                new Hash_Filter("SHA-1")
+                new Chain(new Hash_Filter("SHA-256"), new Hex_Encoder),
+                new Hash_Filter("SHA-512")
                 )
            );
 
@@ -447,40 +449,6 @@ If ``BOTAN_EXT_PIPE_UNIXFD_IO`` is defined, then you can use the
 overloaded I/O operators with Unix file descriptors. For an example of this,
 check out the ``hash_fd`` example, included in the Botan distribution.
 
-A Filter Example
----------------------------------
-
-Here is some code that takes one or more filenames in ``argv`` and
-calculates the result of several hash functions for each file. The complete
-program can be found as ``hasher.cpp`` in the Botan distribution. For
-brevity, error checking has been removed::
-
-   string name[3] = { "MD5", "SHA-1", "RIPEMD-160" };
-   Filter* hash[3] = {
-      new Chain(new Hash_Filter(name[0]),
-                        new Hex_Encoder),
-      new Chain(new Hash_Filter(name[1]),
-                        new Hex_Encoder),
-      new Chain(new Hash_Filter(name[2]),
-                        new Hex_Encoder) };
-
-   Pipe pipe(new Fork(hash, COUNT));
-
-   for(size_t j = 1; argv[j] != 0; j++)
-      {
-      ifstream file(argv[j]);
-      pipe.start_msg();
-      file >> pipe;
-      pipe.end_msg();
-      file.close();
-      for(size_t k = 0; k != 3; k++)
-         {
-         pipe.set_default_msg(3*(j-1)+k);
-         cout << name[k] << "(" << argv[j] << ") = " << pipe << endl;
-         }
-      }
-
-
 Filter Catalog
 ---------------------------------
 
diff --git a/doc/index.txt b/doc/index.txt
index ecbeb8803..18b01e55d 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -16,6 +16,7 @@ Contents:
    lowlevel
    passhash
    rng
+   kdf
    bigint
    examples
    algos
diff --git a/doc/kdf.txt b/doc/kdf.txt
new file mode 100644
index 000000000..de73927d1
--- /dev/null
+++ b/doc/kdf.txt
@@ -0,0 +1,7 @@
+
+.. _key_derivation_functions:
+
+Key Derivation Functions
+========================================
+
+Todo
diff --git a/doc/lowlevel.txt b/doc/lowlevel.txt
index d6bf071bc..8b37345d6 100644
--- a/doc/lowlevel.txt
+++ b/doc/lowlevel.txt
@@ -122,33 +122,33 @@ Block ciphers implement the interface ``BlockCipher``, found in
 
   Returns the block size of the cipher in bytes
 
-.. cpp:function:: void encrypt_n(const byte* in, byte* out, size_t blocks) const
+.. c:function:: void encrypt_n(const byte in[], byte out[], size_t blocks) const
 
   Encrypt ``blocks`` blocks of data, taking the input from ``in`` and
   placing the ciphertext in ``out``. The two pointers may be
   identical, but should not overlap ranges.
 
-.. cpp:function:: void encrypt(const byte* in, byte* out) const
+.. c:function:: void encrypt(const byte in[], byte out[]) const
 
   Encrypt a single block, taking the input from ``in`` and placing it
   in ``out``.
 
-.. cpp:function:: void encrypt(byte* block) const
+.. c:function:: void encrypt(byte block[]) const
 
   Identical to ``encrypt(block, block)``.
 
-.. cpp:function:: void decrypt_n(const byte* in, byte* out, size_t blocks) const
+.. c:function:: void decrypt_n(const byte in[], byte out[], size_t blocks) const
 
   Decrypt ``blocks`` blocks of data, taking the input from ``in`` and
   placing the plaintext in ``out``. The two pointers may be identical,
   but should not overlap ranges.
 
-.. cpp:function:: void decrypt(const byte* in, byte* out) const
+.. c:function:: void decrypt(const byte in[], byte out[]) const
 
   Decrypt a single block, taking the input from ``in`` and placing it
   in ``out``.
 
-.. cpp:function:: void decrypt(byte* block) const
+.. c:function:: void decrypt(byte block[]) const
 
   Identical to ``decrypt(block, block)``.
 
diff --git a/doc/old/tutorial2.tex b/doc/old/tutorial2.tex
deleted file mode 100644
index 840679d10..000000000
--- a/doc/old/tutorial2.tex
+++ /dev/null
@@ -1,141 +0,0 @@
-\documentclass{article}
-
-\setlength{\textwidth}{6.5in} % 1 inch side margins
-\setlength{\textheight}{9in} % ~1 inch top and bottom margins
-
-\setlength{\headheight}{0in}
-\setlength{\topmargin}{0in}
-\setlength{\headsep}{0in}
-
-\setlength{\oddsidemargin}{0in}
-\setlength{\evensidemargin}{0in}
-
-\title{\textbf{Botan Tutorial}}
-\author{Jack Lloyd \\
-        \texttt{[email protected]}}
-\date{2010/08/07}
-
-\newcommand{\filename}[1]{\texttt{#1}}
-\newcommand{\manpage}[2]{\texttt{#1}(#2)}
-
-\newcommand{\macro}[1]{\texttt{#1}}
-
-\newcommand{\function}[1]{\textbf{#1}}
-\newcommand{\type}[1]{\texttt{#1}}
-\renewcommand{\arg}[1]{\textsl{#1}}
-\newcommand{\variable}[1]{\textsl{#1}}
-
-\begin{document}
-
-\maketitle
-
-\tableofcontents
-
-\parskip=5pt
-\pagebreak
-
-\section{Introduction}
-
-This document essentially sets up various simple scenarios and then
-shows how to solve the problems using botan. It's fairly simple, and
-doesn't cover many of the available APIs and algorithms, especially
-the more obscure or unusual ones. It is a supplement to the API
-documentation and the example applications, which are included in the
-distribution.
-
-\section{Initializing the Library}
-
-The first step to using botan is to create a \type{LibraryInitializer}
-object, which handles creating various internal structures, and also
-destroying them at shutdown.
-
-\begin{verbatim}
-#include <botan/botan.h>
-
-int main()
-   {
-   Botan::LibraryInitializer init;
-   return 0;
-   }
-\end{verbatim}
-
-If your application is multi-threaded, you need to tell botan this so
-that it will use locking where necessary. This is done by passing a
-string to the constructor of \type{LibraryInitializer}:
-
-\begin{verbatim}
-    Botan::LibraryInitializer init("thread_safe=yes");
-\end{verbatim}
-
-\section{Introduction to Pipe}
-
-Most operations in botan are specified in terms of transformations on
-streams. The class that handles the I/O and management for these
-streams is called \type{Pipe}. You can construct a \type{Pipe} with
-one or more \type{Filter}s, which sequentially process messages. You
-can only update a single message at a time, but you can leave the
-final output contents in a \type{Pipe} and read them out as desired.
-
-Here is how you might hex encode two messages:
-
-\begin{verbatim}
-   std::string message1 = "this is the first message";
-   const byte message2[] = "a second message";
-   Pipe pipe(new Hex_Encoder);
-
-   pipe.start_msg(); // must be called before writing to the pipe
-   pipe.write(message1);
-   pipe.end_msg(); // must be called to signal completion
-
-   /*
-   process_msg(x) is equivalent to calling
-      start_msg(); write(x); end_msg();
-   */
-   pipe.process_msg(message2);
-
-   Pipe::message_id n = pipe.message_count(); // returns 2
-
-   /* you can read a message as a string, here we read message 0 */
-   std::string first_result = pipe.read_all_as_string(0);
-
-   /* or a piece at a time using array/length, now we'll read the
-      second message (message id 1)
-   */
-
-   byte output[4096] = { 0 };
-   u32bit got = read(output, sizeof(output), 1);
-   if(got >= sizeof(output))
-     // have to read again to get more of the message
-\end{verbatim}
-
-You can also read output while the message is still active (before the
-call to \function{end\_msg}), using the same interfaces. You can find
-out how much data is currently available for a particular \type{Pipe}
-by calling the member function \function{remaining}, which takes a
-message sequence number and returns the number of bytes that are
-currently available to read from that message.
-
-\section{Hashing a File}
-
-Hashing a file is done using a \type{Hash\_Filter}, which takes a string
-which specifies which hash function you want to use:
-
-\begin{verbatim}
-   Pipe pipe(new Hash_Filter("SHA-256"));
-\end{verbatim}
-
-The output of a \type{Hash\_Filter} is raw binary. The filter will not
-produce any output at all until you call \function{end\_msg}.
-
-\section{Symmetric Cryptography}
-
-
-
-\subsection{Authentication}
-
-\subsection{User Authentication}
-
-\section{Public Key Cryptography}
-
-
-\end{document}
diff --git a/doc/passhash.txt b/doc/passhash.txt
index a7a18ebb4..b19d8d4ed 100644
--- a/doc/passhash.txt
+++ b/doc/passhash.txt
@@ -2,7 +2,7 @@
 .. _pbkdf:
 
 PBKDF Algorithms
----------------------------------
+========================================
 
 There are various procedures (usually ad-hoc) for turning a
 passphrase into a (mostly) arbitrary length key for a symmetric
@@ -25,7 +25,7 @@ retrieve any of these using the ``get_pbkdf``, found in
 iterations and a 16 byte salt is recommend for new applications.
 
 OpenPGP S2K
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------
 
 There are some oddities about OpenPGP's S2K algorithms that are
 documented here. For one thing, it uses the iteration count in a
@@ -47,7 +47,7 @@ iteration count is highly recommended to prevent password guessing
 attempts.
 
 Password Hashing
----------------------------------
+========================================
 
 Storing passwords for user authentication purposes in plaintext is the
 simplest but least secure method; when an attacker compromises the
@@ -100,53 +100,51 @@ only test at a rate of .0001% of what they would without iterations
 (or, equivalently, will require 100,000 times as many zombie botnet
 hosts).
 
-There are many different ways of doing this password hashing
-operation, with common ones including Unix's crypt (which is based on
-DES) and OpenBSD's bcrypt (based on Blowfish). Other variants using
-MD5 or SHA-256 are also in use on various systems.
+Botan provides two techniques for password hashing, bcrypt and
+passhash9.
 
-Botan provides two techniques, passhash9 and bcrypt
+Bcrypt
+----------------------------------------
 
-Passhash9
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Bcrypt is a password hashing scheme originally designed for use in
+OpenBSD, but numerous other implementations exist. It is made
+available by including ``bcrypt.h``. Bcrypt provides outputs that
+look like this::
 
-Botan provides a password hashing technique called passhash9, in
-``passhash9.h``, which is based on PBKDF2. A usage example can be
-found in ``doc/examples/passhash.cpp``. Three functions are provided
-in this header:
+  "$2a$12$7KIYdyv8Bp32WAvc.7YvI.wvRlyVn0HP/EhPmmOyMQA4YKxINO0p2"
 
-.. cpp:function:: std::string generate_passhash9(const std::string& password, RandomNumberGenerator& rng, u16bit work_factor = 10)
+.. cpp:function:: std::string generate_bcrypt(const std::string& password, RandomNumberGenerator& rng, u16bit work_factor = 10)
 
-   Takes the password to hash, a rng, and a work factor, which tells
-   how many iterations to compute. The default work factor is 10
-   (which means 100,000 iterations), but any non-zero value is
-   accepted.
+   Takes the password to hash, a rng, and a work factor. Higher values
+   increase the amount of time the algorithm runs, increasing the cost
+   of cracking attempts. The resulting hash is returned as a string.
 
-.. cpp:function:: std::string generate_passhash9(const std::string& password, byte alg_id, RandomNumberGenerator& rng, u16bit work_factor = 10)
+.. cpp:function:: bool check_bcrypt(const std::string& password, const std::string& hash)
 
-   Like the other ``generate_passhash9``, but taking a parameter that
-   specifies which PRF to use. Currently defined values are 0
-   ("HMAC(SHA-1)"), 1 ("HMAC(SHA-256)"), and 2 ("CMAC(Blowfish)").
+   Takes a password and a bcrypt output and returns true if the
+   password is the same as the one that was used to generate the
+   bcrypt hash.
 
-.. cpp:function:: bool check_passhash9(const std::string& password, const std::string& hash)
+Here is an example of using bcrypt:
 
-   Takes a password and a passhash9 output and checks if the password
-   is the same as the one that was used to generate the passhash9
-   output, returning a boolean true (same) or false (not same).
+.. literalinclude: examples/bcrypt.cpp
 
-Bcrypt
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Passhash9
+----------------------------------------
 
-Bcrypt is a password hashing scheme originally designed for use in
-OpenBSD, but numerous other implementations exist. It is made
-available by including ``bcrypt.h``, and provides the functions
+Botan also provides a password hashing technique called passhash9, in
+``passhash9.h``, which is based on PBKDF2.
 
-.. cpp:function:: std::string generate_bcrypt(const std::string& password, RandomNumberGenerator& rng, u16bit work_factor = 10)
+.. cpp:function:: std::string generate_passhash9(const std::string& password, RandomNumberGenerator& rng, u16bit work_factor = 10)
 
-and
+   Functions much like ``generate_bcrypt``
 
-.. cpp:function:: bool check_bcrypt(const std::string& password, const std::string& hash)
+.. cpp:function:: std::string generate_passhash9(const std::string& password, byte alg_id, RandomNumberGenerator& rng, u16bit work_factor = 10)
+
+   Like the other ``generate_passhash9``, but taking a parameter that
+   specifies which PRF to use. Currently defined values are 0
+   ("HMAC(SHA-1)"), 1 ("HMAC(SHA-256)"), and 2 ("CMAC(Blowfish)").
 
-These work in exactly the same way as the passhash9 password hashing
-functions.
+.. cpp:function:: bool check_passhash9(const std::string& password, const std::string& hash)
 
+   Functions much like ``check_bcrypt``
diff --git a/doc/pubkey.txt b/doc/pubkey.txt
index 2089434d6..6279234e9 100644
--- a/doc/pubkey.txt
+++ b/doc/pubkey.txt
@@ -300,7 +300,7 @@ plaintext twice produces two different ciphertexts.
 The primary interface for encryption is ``PK_Encryptor``, which
 provides the following interface:
 
-.. cpp:function:: SecureVector<byte> PK_Encryptor::encrypt(const byte in[], size_t length, RandomNumberGenerator& rng) const
+.. cpp:function:: SecureVector<byte> PK_Encryptor::encrypt(const byte* in, size_t length, RandomNumberGenerator& rng) const
 
 .. cpp:function:: SecureVector<byte> PK_Encryptor::encrypt(const MemoryRegion<byte>& in, RandomNumberGenerator& rng) const
 
diff --git a/doc/ssl.txt b/doc/ssl.txt
index dd206d5fc..8f2ad3a2a 100644
--- a/doc/ssl.txt
+++ b/doc/ssl.txt
@@ -1,10 +1,26 @@
 
-SSL/TLS
+SSL and TLS
 ========================================
 
-SSL/TLS Clients
+Botan supports both client and server implementations of the SSL/TLS
+protocols, including SSL v3, TLS v1.0, and TLS v1.1. The insecure and
+obsolete SSL v2 is not supported.
+
+The implementation uses ``std::tr1::function``, so it may not have
+been compiled into the version you are using; you can test for the
+feature macro ``BOTAN_HAS_SSL_TLS`` to check.
+
+TLS Clients
 ----------------------------------------
 
+A simple TLS client:
+
+.. literalinclude:: examples/tls_client.cpp
 
-SSL/TLS Servers
+
+TLS Servers
 ----------------------------------------
+
+A simple TLS server
+
+.. literalinclude:: examples/tls_server.cpp