Tick version numbers to 1.10.0

More documentation updates.

The clean target wasn't removing one of the symlinks.

In the self-test application, warn if the version we are linked
against does not match the version we were built against. This
always indicates a problem. Someone who had an older version
installed on their system got very confused when the test app was
linked against it at runtime; this warning would have saved a
couple hours of puzzling by me. This would also have helped avoid
the nasty bug in 1.8.3

4 files changed, 78 insertions, 107 deletions

diff --git a/doc/license.txt b/doc/license.txt
index 33b2f5982..aefcee395 100644
--- a/doc/license.txt
+++ b/doc/license.txt
@@ -1,5 +1,6 @@
 
 .. _license:
+.. highlight:: none
 
 License
 ========================================
diff --git a/doc/log.txt b/doc/log.txt
index 44da4d430..ee0526f36 100644
--- a/doc/log.txt
+++ b/doc/log.txt
@@ -5,6 +5,11 @@ Release Notes
 2011
 ----------------------------------------
 
+Version 1.10.0, Not Yet Released
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * More updates to the documentation
+
 Version 1.9.16, 2011-04-11
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/doc/lowlevel.txt b/doc/lowlevel.txt
index 8b37345d6..9f1c7bc42 100644
--- a/doc/lowlevel.txt
+++ b/doc/lowlevel.txt
@@ -16,21 +16,21 @@ Basic Algorithm Abilities
 There are a small handful of functions implemented by most of Botan's
 algorithm objects. Among these are:
 
-.. cpp:function:: std::string name()
+.. cpp:function:: std::string Algorithm::name()
 
 Returns a human-readable string of the name of this
 algorithm. Examples of names returned are "AES-128" and
 "HMAC(SHA-512)". You can turn names back into algorithm objects using
 the functions in ``lookup.h``.
 
-.. cpp:function:: void clear()
+.. cpp:function:: void Algorithm::clear()
 
 Clear out the algorithm's internal state. A block cipher object will
 "forget" its key, a hash function will "forget" any data put into it,
 etc. The object will look and behave as it did when you initially
 allocated it.
 
-.. cpp:function:: T* clone()
+.. cpp:function:: T* Algorithm::clone()
 
 This function is central to Botan's name-based interface. The
 ``clone`` has many different return types, such as ``BlockCipher``\*
@@ -84,7 +84,7 @@ those types are derived from the ``SymmetricAlgorithm`` base
 class. This type provides functions for setting the key, and querying
 restrictions on the size of the key:
 
-.. cpp:function:: void set_key(const byte* key, size_t length)
+.. cpp:function:: void SymmetricAlgorithm::set_key(const byte* key, size_t length)
 
   This sets the key to the value specified. Most algorithms only
   accept keys of certain lengths. If you attempt to call ``set_key``
@@ -97,17 +97,17 @@ restrictions on the size of the key:
   object. If this is not done, the results are undefined, but probably
   will not be good.
 
-.. cpp:function:: bool valid_keylength(size_t length) const
+.. 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.
 
-.. cpp:function:: size_t minimum_keylength() const
+.. cpp:function:: size_t SymmetricAlgorithm::minimum_keylength() const
 
   Return the smallest key length (in bytes) that is acceptible for the
   algorithm.
 
-.. cpp:function:: size_t maximum_keylength() const
+.. cpp:function:: size_t SymmetricAlgorithm::maximum_keylength() const
 
   Return the largest key length (in bytes) that is acceptible for the
   algorithm
@@ -118,37 +118,37 @@ Block Ciphers
 Block ciphers implement the interface ``BlockCipher``, found in
 ``block_cipher.h``, as well as the ``SymmetricAlgorithm`` interface.
 
-.. cpp:function:: size_t block_size() const
+.. cpp:function:: size_t BlockCipher::block_size() const
 
   Returns the block size of the cipher in bytes
 
-.. c:function:: void encrypt_n(const byte in[], byte out[], size_t blocks) const
+.. cpp:function:: void BlockCipher::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.
 
-.. c:function:: void encrypt(const byte in[], byte out[]) const
+.. 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``.
 
-.. c:function:: void encrypt(byte block[]) const
+.. cpp:function:: void BlockCipher::encrypt(byte* block) const
 
   Identical to ``encrypt(block, block)``.
 
-.. c:function:: void decrypt_n(const byte in[], byte out[], size_t blocks) const
+.. cpp:function:: void BlockCipher::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.
 
-.. c:function:: void decrypt(const byte in[], byte out[]) const
+.. 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``.
 
-.. c:function:: void decrypt(byte block[]) const
+.. cpp:function:: void BlockCipher::decrypt(byte* block) const
 
   Identical to ``decrypt(block, block)``.
 
@@ -161,35 +161,36 @@ encrypting data results in changing the internal state of the
 cipher. Also, you may encrypt any length of data in one go (in byte
 amounts).
 
-.. cpp:function:: void encrypt(const byte* in, byte* out, size_t length)
+.. cpp:function:: void StreamCipher::encrypt(const byte* in, byte* out, size_t length)
 
-.. cpp:function:: void encrypt(byte* data, size_t length)
+.. cpp:function:: void StreamCipher::encrypt(byte* data, size_t length)
 
 Stream ciphers implement the ``SymmetricAlgorithm`` interface.
 
 Hash Functions / Message Authentication Codes
 ----------------------------------------------
 
-Hash functions take their input without producing any output, only producing
-anything when all input has already taken place. MACs are very similar, but are
-additionally keyed. Both of these are derived from the base class
-``BufferedComputation``, which has the following functions.
+Hash functions take their input without producing any output, only
+producing anything when all input has already taken place. MACs are
+very similar, but are additionally keyed. Both of these are derived
+from the base class ``BufferedComputation``, which has the following
+functions.
 
-.. cpp:function:: size_t output_length()
+.. cpp:function:: size_t BufferedComputation::output_length()
 
 Return the size of the output of this function.
 
-.. cpp:function:: void update(const byte* input, size_t length)
+.. cpp:function:: void BufferedComputation::update(const byte* input, size_t length)
 
-.. cpp:function:: void update(byte input)
+.. cpp:function:: void BufferedComputation::update(byte input)
 
-.. cpp:function:: void update(const std::string& input)
+.. cpp:function:: void BufferedComputation::update(const std::string& input)
 
 Updates the hash/mac calculation with ``input``.
 
-.. cpp:function:: void final(byte* out)
+.. cpp:function:: void BufferedComputation::final(byte* out)
 
-.. cpp:function:: SecureVector<byte> final()
+.. cpp:function:: SecureVector<byte> BufferedComputation::final()
 
 Complete the hash/MAC calculation and place the result into ``out``.
 For the argument taking an array, exactly ``output_length`` bytes will
@@ -216,74 +217,16 @@ away; the key is kept around).
 A MAC has the ``SymmetricAlgorithm`` interface in addition to the
 ``BufferedComputation`` interface.
 
-User Interfaces
----------------------------------
-
-Botan has recently changed some infrastructure to better accommodate
-more complex user interfaces, in particular ones that are based on
-event loops. Primary among these was the fact that when doing
-something like loading a PKCS #8 encoded private key, a passphrase
-might be needed, but then again it might not (a PKCS #8 key doesn't
-have to be encrypted). Asking for a passphrase to decrypt an
-unencrypted key is rather pointless. Not only that, but the way to
-handle the user typing the wrong passphrase was complicated,
-undocumented, and inefficient.
-
-So now Botan has an object called ``User_Interface``, which provides a
-simple interface for the aspects of user interaction the library has
-to be concerned with. Currently, this means getting a passphrase from
-the user, and that's it (``User_Interface`` will probably be extended
-in the future to support other operations as they are needed). The
-base ``User_Interface`` class is very stupid, because the library
-can't directly assume anything about the environment that it's running
-under (for example, if there will be someone sitting at the terminal,
-if the application is even *attached* to a terminal, and so on). But
-since you can subclass ``User_Interface`` to use whatever method
-happens to be appropriate for your application, this isn't a big deal:
-
-.. cpp:function:: std::string User_Interface::get_passphrase(const std::string& what, const std::string& source, UI_Result& result) const
-
-  The ``what`` argument specifies what the passphrase is needed for
-  (for example, PKCS #8 key loading passes ``what`` as "PKCS #8
-  private key"). This lets you provide the user with some indication
-  of *why* your application is asking for a passphrase; feel free to
-  pass the string through ``gettext(3)`` or moral equivalent for i18n
-  purposes. Similarly, ``source`` specifies where the data in question
-  came from, if available (for example, a file name). If the source is
-  not available for whatever reason, then ``source`` will be an empty
-  string; be sure to account for this possibility when writing a
-  ``User_Interface`` subclass.
-
-  The function returns the passphrase as the return value, and a
-  status code in ``result`` (either ``OK`` or ``CANCEL_ACTION``). If
-  ``CANCEL_ACTION`` is returned in ``result``, then the return value
-  will be ignored, and the caller will take whatever action is
-  necessary (typically, throwing an exception stating that the
-  passphrase couldn't be determined). In the specific case of PKCS #8
-  key decryption, a ``Decoding_Error`` exception will be thrown; your
-  UI should assume this can happen, and provide appropriate error
-  handling (such as putting up a dialog box informing the user of the
-  situation, and canceling the operation in progress).
-
-There is an example ``User_Interface`` that uses GTK+ available on the
-web site. The ``GTK_UI`` code is cleanly separated from the rest of
-the example, so if you happen to be using GTK+, you can copy (and/or
-adapt) that code for your application. If you write a
-``User_Interface`` object for another windowing system (Win32, Qt,
-wxWidgets, FOX, etc), and would like to make it available to users in
-general (ideally under a permissive license such as public domain or
-MIT/BSD), feel free to send in a copy.
-
-
 Checksums
----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Checksums are very similar to hash functions, and in fact share the same
-interface. But there are some significant differences, the major ones being
-that the output size is very small (usually in the range of 2 to 4 bytes), and
-is not cryptographically secure. But for their intended purpose (error
-checking), they perform very well. Some examples of checksums included in Botan
-are the Adler32 and CRC32 checksums.
+Checksums are very similar to hash functions, and in fact share the
+same interface. But there are some significant differences, the major
+ones being that the output size is very small (usually in the range of
+2 to 4 bytes), and is not cryptographically secure. But for their
+intended purpose (error checking), they perform very well. Some
+examples of checksums included in Botan are the Adler32 and CRC32
+checksums.
 
 Threads and Mutexes
 ---------------------------------
@@ -349,7 +292,7 @@ data into its buffer. Like ``SecureBuffer``, it implements ``clear``
 and ``size``.
 
 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
diff --git a/doc/pubkey.txt b/doc/pubkey.txt
index 07aa0be80..d82ed0f4e 100644
--- a/doc/pubkey.txt
+++ b/doc/pubkey.txt
@@ -174,26 +174,48 @@ you have to create - the other is a simple wrapper functions that take
 either a filename or a memory buffer and create the appropriate
 ``DataSource``.
 
-The versions that pass the passphrase as a ``std::string`` are
-primarily for compatibility, but they are useful in limited
-circumstances. The ``User_Interface`` versions are how ``load_key`` is
-implemented, and provides for much more flexibility. If the passphrase
-passed in is not correct, then an exception is thrown and that is
-that. However, if you pass in an UI object, then the UI object can
-keep asking the user for the passphrase until they get it right (or
-until they cancel the action, though the UI interface). A
-``User_Interface`` has very little to do with talking to users; it's
-just a way to glue together Botan and whatever user interface you
-happen to be using. You can think of it as a user interface
-interface. The default ``User_Interface`` is rather dumb, and acts
-rather like the versions taking the ``std::string``; it tries the
-passphrase passed in first, and then it cancels.
+The versions taking a ``std::string`` attempt to decrypt using the
+password given (if the key is encrypted; if it is not, the passphase
+value will be ignored). If the passphrase does not decrypt the key, an
+exception will be thrown.
+
+The ones taking a ``User_Interface`` provide a simple callback
+interface which makes handling incorrect passphrases and such a bit
+simpler. A ``User_Interface`` has very little to do with talking to
+users; it's just a way to glue together Botan and whatever user
+interface you happen to be using.
 
 .. note::
 
   In a future version, it is likely that ``User_Interface`` will be
   replaced by a simple callback using ``std::function``.
 
+To use ``User_Interface``, derive a subclass and implement:
+
+.. cpp:function:: std::string User_Interface::get_passphrase(const std::string& what, const std::string& source, UI_Result& result) const
+
+  The ``what`` argument specifies what the passphrase is needed for
+  (for example, PKCS #8 key loading passes ``what`` as "PKCS #8
+  private key"). This lets you provide the user with some indication
+  of *why* your application is asking for a passphrase; feel free to
+  pass the string through ``gettext(3)`` or moral equivalent for i18n
+  purposes. Similarly, ``source`` specifies where the data in question
+  came from, if available (for example, a file name). If the source is
+  not available for whatever reason, then ``source`` will be an empty
+  string; be sure to account for this possibility.
+
+  The function returns the passphrase as the return value, and a
+  status code in ``result`` (either ``OK`` or ``CANCEL_ACTION``). If
+  ``CANCEL_ACTION`` is returned in ``result``, then the return value
+  will be ignored, and the caller will take whatever action is
+  necessary (typically, throwing an exception stating that the
+  passphrase couldn't be determined). In the specific case of PKCS #8
+  key decryption, a ``Decoding_Error`` exception will be thrown; your
+  UI should assume this can happen, and provide appropriate error
+  handling (such as putting up a dialog box informing the user of the
+  situation, and canceling the operation in progress).
+
+
 .. _serializing_public_keys:
 
 Serializing Public Keys