Some doc updates, include the DSA examples in pubkey, remove outdated

and probably useless threads section, also fix compilation of several
examples.

10 files changed, 62 insertions, 99 deletions

diff --git a/doc/algos.txt b/doc/algos.txt
index bf2a91b0c..3d4050c11 100644
--- a/doc/algos.txt
+++ b/doc/algos.txt
@@ -73,7 +73,6 @@ primitives, including:
 
     * PRFs from ANSI X9.42, SSL v3.0, TLS v1.0
 
-
 Recommended Algorithms
 ---------------------------------
 
@@ -143,8 +142,8 @@ match that in SCAN, if it's defined there).
 **Stream Ciphers:** "ARC4", "MARK4", "Salsa20", "Turing",
 "WiderWake4+1-BE"
 
-**Hash Functions:** "HAS-160", "GOST-34.11", "MD2", "MD4", "MD5",
-"RIPEMD-128", "RIPEMD-160", "SHA-160", "SHA-256", "SHA-384",
-"SHA-512", "Skein-512", "Tiger(OUTSZ)", "Whirlpool"
+**Hash Functions:** "HAS-160", "GOST-34.11", "Keccak-1600(OUTSZ)",
+"MD2", "MD4", "MD5", "RIPEMD-128", "RIPEMD-160", "SHA-160", "SHA-256",
+"SHA-384", "SHA-512", "Skein-512", "Tiger(OUTSZ)", "Whirlpool"
 
 **MACs:** "HMAC(HASH)", "CMAC(BLOCK)", "X9.19-MAC"
diff --git a/doc/conf.py b/doc/conf.py
index e0600da81..f4884cb69 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -80,7 +80,7 @@ exclude_patterns = ['_build']
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+add_function_parentheses = False
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
@@ -190,7 +190,7 @@ htmlhelp_basename = 'botandoc'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'botan.tex', u'botan Documentation',
+  ('index', 'botan.tex', u'botan Reference Manual',
    u'Jack Lloyd', 'manual'),
 ]
 
@@ -203,10 +203,10 @@ latex_documents = [
 #latex_use_parts = False
 
 # If true, show page references after internal links.
-#latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
-#latex_show_urls = False
+latex_show_urls = True
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
diff --git a/doc/examples.txt b/doc/examples.txt
index e0fd3ab40..b9296829a 100644
--- a/doc/examples.txt
+++ b/doc/examples.txt
@@ -2,24 +2,6 @@
 Examples
 ========================================
 
-DSA Examples
-----------------------------------------
-
-DSA Signature Generation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Reads a DSA private key and signs the specified file using SHA-1
-
-.. literalinclude:: examples/dsa_sign.cpp
-
-DSA Signature Verification
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Reads a DSA public key and a signature, and checks if the signature
-is valid for the specified file
-
-..literalinclude:: examples/dsa_ver.cpp
-
 X.509 Certificate Examples
 ----------------------------------------
 
@@ -52,18 +34,6 @@ expected in "cacert.pem", the private key is expected in
 
 .. literalinclude:: examples/ca.cpp
 
-
-Format Preserving Encryption
-----------------------------------------
-
-Format preserving encryption is a way of mapping data with an
-arbitrarily specified format such that the ciphertext has the same
-formatting. This example encrypts a credit card number with a valid
-`Luhn checksum <http://en.wikipedia.org/wiki/Luhn_algorithm>`_ to
-another number with the same format, including a correct checksum.
-
-.. literalinclude:: examples/fpe.cpp
-
 ASN.1 Parsing
 ----------------------------------------
 
diff --git a/doc/examples/asn1.cpp b/doc/examples/asn1.cpp
index bb891d746..95e5b2627 100644
--- a/doc/examples/asn1.cpp
+++ b/doc/examples/asn1.cpp
@@ -21,8 +21,8 @@ using namespace Botan;
 */
 #define INITIAL_LEVEL 0
 
-void decode(BER_Decoder&, u32bit);
-void emit(const std::string&, u32bit, u32bit, const std::string& = "");
+void decode(BER_Decoder&, size_t);
+void emit(const std::string&, size_t, size_t, const std::string& = "");
 std::string type_name(ASN1_Tag);
 
 int main(int argc, char* argv[])
@@ -243,7 +243,7 @@ void emit(const std::string& type, size_t level, size_t length,
    const size_t BIN_LIMIT = 64;
 
    int written = 0;
-   written += printf("  d=%2d, l=%4d: ", level, length);
+   written += printf("  d=%2d, l=%4d: ", (int)level, (int)length);
    for(size_t i = INITIAL_LEVEL; i != level; ++i)
       written += printf(" ");
    written += printf("%s   ", type.c_str());
diff --git a/doc/examples/dh.cpp b/doc/examples/dh.cpp
index 8489df8fe..8d163303a 100644
--- a/doc/examples/dh.cpp
+++ b/doc/examples/dh.cpp
@@ -33,11 +33,11 @@ int main()
 
       // Now Alice performs the key agreement operation
       PK_Key_Agreement ka_alice(private_a, "KDF2(SHA-256)");
-      SymmetricKey alice_key = ka1.derive_key(32, public_b, session_param);
+      SymmetricKey alice_key = ka_alice.derive_key(32, public_b, session_param);
 
       // Bob does the same:
       PK_Key_Agreement ka_bob(private_b, "KDF2(SHA-256)");
-      SymmetricKey bob_key = ka2.derive_key(32, public_a, session_param);
+      SymmetricKey bob_key = ka_bob.derive_key(32, public_a, session_param);
 
       if(alice_key == bob_key)
          {
diff --git a/doc/examples/dsa_sign.cpp b/doc/examples/dsa_sign.cpp
index 827fc7e0a..3511eacfa 100644
--- a/doc/examples/dsa_sign.cpp
+++ b/doc/examples/dsa_sign.cpp
@@ -7,6 +7,7 @@
 #include <botan/botan.h>
 #include <botan/pubkey.h>
 #include <botan/dsa.h>
+#include <botan/base64.h>
 using namespace Botan;
 
 const std::string SUFFIX = ".sig";
diff --git a/doc/examples/tls_client.cpp b/doc/examples/tls_client.cpp
index 6c5ad7bde..eb4a98817 100644
--- a/doc/examples/tls_client.cpp
+++ b/doc/examples/tls_client.cpp
@@ -1,4 +1,4 @@
-#include <botan/init.h>
+#include <botan/botan.h>
 #include <botan/tls_client.h>
 #include "socket.h"
 
diff --git a/doc/index.txt b/doc/index.txt
index 081f065ba..ca3795e88 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -18,6 +18,7 @@ Contents:
    passhash
    rng
    kdf
+   fpe
    bigint
    examples
    algos
diff --git a/doc/lowlevel.txt b/doc/lowlevel.txt
index 9f1c7bc42..5b3ec42b2 100644
--- a/doc/lowlevel.txt
+++ b/doc/lowlevel.txt
@@ -57,13 +57,13 @@ Since often it's hard to distinguish between a key and IV, many things
 
 .. cpp:function:: OctetString::OctetString(RandomNumberGenerator& rng, size_t length)
 
-  This constructor creates a new random key ``length`` bytes long
-  using the random number generator.
+  This constructor creates a new random key *length* bytes long using
+  the random number generator.
 
 .. cpp:function:: OctetString::OctetString(std::string str)
 
-  The argument ``str`` is assumed to be a hex string; it is converted
-  to binary and stored. Whitespace is ignored.
+  The argument *str* is assumed to be a hex string; it is converted to
+  binary and stored. Whitespace is ignored.
 
 .. cpp:function:: OctetString::OctetString(const byte* input, size_t length)
 
@@ -99,8 +99,8 @@ restrictions on the size of the key:
 
 .. cpp:function:: bool SymmetricAlgorithm::valid_keylength(size_t length) const
 
-  This function returns true if and only if ``length`` is a valid keylength
-  for the algorithm.
+  This function returns true if and only if *length* is a valid
+  keylength for the algorithm.
 
 .. cpp:function:: size_t SymmetricAlgorithm::minimum_keylength() const
 
@@ -122,35 +122,35 @@ Block ciphers implement the interface ``BlockCipher``, found in
 
   Returns the block size of the cipher in bytes
 
-.. cpp:function:: void BlockCipher::encrypt_n(const byte* in, byte* out, size_t blocks) const
+.. cpp:function:: void BlockCipher::encrypt_n(const byte* in, byte* out, size_t n) const
 
-  Encrypt ``blocks`` blocks of data, taking the input from ``in`` and
-  placing the ciphertext in ``out``. The two pointers may be
+  Encrypt *n* blocks of data, taking the input from the array *in* and
+  placing the ciphertext into *out*. The two pointers may be
   identical, but should not overlap ranges.
 
 .. cpp:function:: void BlockCipher::encrypt(const byte* in, byte* out) const
 
-  Encrypt a single block, taking the input from ``in`` and placing it
-  in ``out``.
+  Encrypt a single block, taking the input from *in* and placing it
+  in *out*. Acts like :cpp:func:`encrypt_n`\ (in, out, 1).
 
 .. cpp:function:: void BlockCipher::encrypt(byte* block) const
 
-  Identical to ``encrypt(block, block)``.
+  Identical to :cpp:func:`encrypt`\ (block, block)
 
-.. cpp:function:: void BlockCipher::decrypt_n(const byte* in, byte out, size_t blocks) const
+.. cpp:function:: void BlockCipher::decrypt_n(const byte* in, byte out, size_t n) 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.
+  Decrypt *n* 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 BlockCipher::decrypt(const byte* in, byte* out) const
 
-  Decrypt a single block, taking the input from ``in`` and placing it
-  in ``out``.
+  Decrypt a single block, taking the input from *in* and placing it
+  in *out*. Acts like :cpp:func:`decrypt_n`\ (in, out, 1).
 
 .. cpp:function:: void BlockCipher::decrypt(byte* block) const
 
-  Identical to ``decrypt(block, block)``.
+  Identical to :cpp:func:`decrypt`\ (block, block)
 
 
 Stream Ciphers
@@ -186,7 +186,7 @@ Return the size of the output of this function.
 
 .. cpp:function:: void BufferedComputation::update(const std::string& input)
 
-Updates the hash/mac calculation with ``input``.
+Updates the hash/mac calculation with *input*.
 
 .. cpp:function:: void BufferedComputation::final(byte* out)
 
@@ -228,22 +228,6 @@ intended purpose (error checking), they perform very well. Some
 examples of checksums included in Botan are the Adler32 and CRC32
 checksums.
 
-Threads and Mutexes
----------------------------------
-
-Botan includes a mutex system, which is used internally to lock some shared
-data structures that must be kept shared for efficiency reasons (mostly, these
-are in the allocation systems~--~handing out 1000 separate allocators hurts
-performance and makes caching memory blocks useless). This system is supported
-by the ``mux_pthr`` module, implementing the ``Mutex`` interface for
-systems that have POSIX threads.
-
-If your application is using threads, you *must* add the option
-"thread_safe" to the options string when you create the
-``LibraryInitializer`` object. If you specify this option and no mutex
-type is available, an exception is thrown, since otherwise you would
-probably be facing a nasty crash.
-
 Secure Memory
 ---------------------------------
 
@@ -279,17 +263,18 @@ These types are not described in any great detail: for more information,
 consult the definitive sources~--~the header files ``secmem.h`` and
 ``allocate.h``.
 
-``SecureBuffer`` is a simple array type, whose size is specified at compile
-time. It will automatically convert to a pointer of the appropriate type, and
-has a number of useful functions, including ``clear()``, and
-``size_t`` ``size()``, which returns the length of the array. It is a
-template that takes as parameters a type, and a constant integer which is how
-long the array is (for example: ``SecureBuffer<byte, 8> key;``).
+``SecureBuffer`` is a simple array type, whose size is specified at
+compile time. It will automatically convert to a pointer of the
+appropriate type, and has a number of useful functions, including
+``clear()``, and ``size_t`` ``size()``, which returns the length of
+the array. It is a template that takes as parameters a type, and a
+constant integer which is how long the array is (for example:
+``SecureBuffer<byte, 8> key;``).
 
-``SecureVector`` is a variable length array. Its size can be increased or
-decreased as need be, and it has a wide variety of functions useful for copying
-data into its buffer. Like ``SecureBuffer``, it implements ``clear``
-and ``size``.
+``SecureVector`` is a variable length array. Its size can be increased
+or decreased as need be, and it has a wide variety of functions useful
+for copying data into its buffer. Like ``SecureBuffer``, it implements
+``clear`` and ``size``.
 
 Allocators
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -297,14 +282,14 @@ Allocators
 The containers described above get their memory from allocators. As a
 user of the library, you can add new allocator methods at run time for
 containers, including the ones used internally by the library, to
-use. The interface to this is in ``allocate.h``. Code needing
-to allocate or deallocate memory calls ``get_allocator``,
-which returns a pointer to an allocator object. This pointer should
-not be freed: the caller does not own the allocator (it is shared
-among multiple allocatore users, and uses a mutex to serialize access
-internally if necessary). It is possible to call
-``get_allocator`` with a specific name to request a particular
-type of allocator, otherwise, a default allocator type is returned.
+use. The interface to this is in ``allocate.h``. Code needing to
+allocate or deallocate memory calls ``get_allocator``, which returns a
+pointer to an allocator object. This pointer should not be freed: the
+caller does not own the allocator (it is shared among multiple
+allocatore users, and uses a mutex to serialize access internally if
+necessary). It is possible to call ``get_allocator`` with a specific
+name to request a particular type of allocator, otherwise, a default
+allocator type is returned.
 
 At start time, the only allocator known is a ``Default_Allocator``,
 which just allocates memory using ``malloc``, and zeroizes it when the
@@ -323,4 +308,3 @@ allocator was successfully registered. If you ask it to,
 Finally, you can set the default allocator type that will be returned
 using the policy setting "default_alloc" to the name of any previously
 registered allocator.
-
diff --git a/doc/pubkey.txt b/doc/pubkey.txt
index f48f28340..fe24c719b 100644
--- a/doc/pubkey.txt
+++ b/doc/pubkey.txt
@@ -458,6 +458,14 @@ For DSA, ECDSA, GOST-34.11, and Nyberg-Rueppel, you should use
 EMSA1. None of the other encoding methods are particularly useful for
 these algorithms.
 
+Here is an example of DSA signature generation
+
+.. literalinclude:: examples/dsa_sign.cpp
+
+Here is an example that verifies DSA signatures
+
+.. literalinclude:: examples/dsa_ver.cpp
+
 Key Agreement
 ---------------------------------