Convert most of the documentation to reStructured Text, adding

a makefile to build it with Sphinx (http://sphinx.pocoo.org/).

Previously credits.txt listed public domain code sources; instead
directly credit the authors in the relevant files and delete that
file.

Drop the draft FIPS 140 security policy; I can't imagine FIPS 140
validation will ever happen, and if it does, I don't want
anything to do with it.

Also drop the internals doc, which was so out of date (and
incomplete) as to be worthless.

Move the tutorials and InSiTo pdfs into old/ for the time being,
until anything relevant from them can be filtered out and
converted into RST.

102 files changed, 5485 insertions, 5705 deletions

diff --git a/botan_version.py b/botan_version.py
new file mode 100644
index 000000000..ff1b7c22b
--- /dev/null
+++ b/botan_version.py
@@ -0,0 +1,8 @@
+
+major = 1
+minor = 9
+patch = 16
+
+so_patch = 16
+release_suffix = '-dev'
+datestamp = 0
diff --git a/configure.py b/configure.py
index 7858c7464..d773244df 100755
--- a/configure.py
+++ b/configure.py
@@ -30,6 +30,12 @@ import getpass
 import time
 import errno
 
+# Avoid useless botan_version.pyc (Python 2.6 or higher)
+if 'dont_write_bytecode' in sys.__dict__:
+    sys.dont_write_bytecode = True
+
+import botan_version
+
 from optparse import (OptionParser, OptionGroup,
                       IndentedHelpFormatter, SUPPRESS_HELP)
 
@@ -41,13 +47,13 @@ class BuildConfigurationInformation(object):
     """
     Version information
     """
-    version_major = 1
-    version_minor = 9
-    version_patch = 16
-    version_so_patch = 16
-    version_suffix = '-dev'
+    version_major = botan_version.major
+    version_minor = botan_version.minor
+    version_patch = botan_version.patch
+    version_so_patch = botan_version.so_patch
+    version_suffix = botan_version.release_suffix
 
-    version_datestamp = 0
+    version_datestamp = botan_version.datestamp
 
     version_string = '%d.%d.%d%s' % (
         version_major, version_minor, version_patch, version_suffix)
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 000000000..152fa3e09
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,60 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html singlehtml latex latexpdf text man
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
diff --git a/doc/algos.txt b/doc/algos.txt
new file mode 100644
index 000000000..0221405d6
--- /dev/null
+++ b/doc/algos.txt
@@ -0,0 +1,78 @@
+Algorithms
+=================================
+
+Recommended Algorithms
+---------------------------------
+
+This section is by no means the last word on selecting which
+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
+were evaluated when making this list: security, standardization,
+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.
+
+ - Block ciphers: AES or Serpent in CBC, CTR, or XTS mode
+
+ - Hash functions: SHA-256, SHA-512
+
+ - MACs: HMAC with any recommended hash function
+
+ - 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)"
+
+ - 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
+to use them. However, you do need to know what string (or strings) are
+used to identify that algorithm. These names conform to those set out
+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/
+
+Many of these algorithms can take options (such as the number of
+rounds in a block cipher, the output size of a hash function,
+etc). These are shown in the following list; all of them default to
+reasonable values. There are algorithm-specific limits on most of
+them. When you see something like "HASH" or "BLOCK", that means
+you should insert the name of some algorithm of that type. There are
+no defaults for those options.
+
+A few very obscure algorithms are skipped; if you need one of them,
+you'll know it, and you can look in the appropriate header to see what
+that classes' ``name`` function returns (the names tend to
+match that in SCAN, if it's defined there).
+
+ - ROUNDS: The number of rounds in a block cipher.
+ - OUTSZ: The output size of a hash function or MAC
+
+**Block Ciphers:** "AES-128", "AES-192", "AES-256", "Blowfish",
+"CAST-128", "CAST-256", "DES", "DESX", "TripleDES", "GOST-28147-89",
+"IDEA", "KASUMI", "MARS", "MISTY1(ROUNDS)", "Noekeon", "RC2",
+"RC5(ROUNDS)", "RC6", "SAFER-SK(ROUNDS)", "SEED", "Serpent",
+"Skipjack", "Square", "TEA", "Twofish", "XTEA"
+
+**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"
+
+**MACs:** "HMAC(HASH)", "CMAC(BLOCK)", "X9.19-MAC"
diff --git a/doc/api.tex b/doc/api.tex
deleted file mode 100644
index 434b717e4..000000000
--- a/doc/api.tex
+++ /dev/null
@@ -1,2959 +0,0 @@
-\documentclass{article}
-
-\setlength{\textwidth}{6.5in}
-\setlength{\textheight}{9in}
-
-\setlength{\headheight}{0in}
-\setlength{\topmargin}{0in}
-\setlength{\headsep}{0in}
-
-\setlength{\oddsidemargin}{0in}
-\setlength{\evensidemargin}{0in}
-
-\title{\textbf{Botan Reference Manual}}
-\author{}
-\date{2010/06/14}
-
-\newcommand{\filename}[1]{\texttt{#1}}
-\newcommand{\manpage}[2]{\texttt{#1}(#2)}
-
-\newcommand{\macro}[1]{\texttt{#1}}
-
-\newcommand{\function}[1]{\textbf{#1}}
-\newcommand{\keyword}[1]{\texttt{#1}}
-\newcommand{\type}[1]{\texttt{#1}}
-\renewcommand{\arg}[1]{\textsl{#1}}
-\newcommand{\namespace}[1]{\texttt{#1}}
-
-\newcommand{\url}[1]{\texttt{#1}}
-
-\newcommand{\ie}[0]{\emph{i.e.}}
-\newcommand{\eg}[0]{\emph{e.g.}}
-
-\begin{document}
-
-\maketitle
-
-\tableofcontents
-
-\parskip=5pt
-
-\pagebreak
-
-\section{Introduction}
-
-Botan is a C++ library that attempts to provide the most common
-cryptographic algorithms and operations in an easy to use, efficient,
-and portable way. It runs on a wide variety of systems, and can be
-used with a number of different compilers.
-
-The base library is written in ISO C++, so it can be ported with
-minimal fuss, but Botan also supports a modules system. This system
-exposes system dependent code to the library through portable
-interfaces, extending the set of services available to users.
-
-\subsection{Recommended Reading}
-
-It's a very good idea if you have some knowledge of cryptography prior
-to trying to use this stuff. You really should read at least one and
-ideally all of these books before seriously using the library.
-
-\setlength{\parskip}{5pt}
-
-\noindent
-\textit{Cryptography Engineering}, Niels Ferguson, Bruce Schneier, and
-Tadayoshi Kohno; Wiley
-
-\noindent
-\textit{Security Engineering -- A Guide to Building Dependable
-  Distributed Systems}, Ross Anderson; Wiley
-
-\noindent
-\textit{Handbook of Applied Cryptography}, Alfred J. Menezes,
-Paul C. Van Oorschot, and Scott A. Vanstone; CRC Press (available
-online at \url{http://www.cacr.math.uwaterloo.ca/hac/})
-
-\subsection{Targets}
-
-Botan's primary targets (system-wise) are 32 and 64-bit CPUs, with a
-flat memory address space of at least 32 bits. Given the choice
-between optimizing for 32-bit systems and 64-bit systems, Botan is
-written to prefer 64-bit, on the theory that where performance is a
-real concern, modern 64-bit processors are the obvious choice.
-
-Smaller handhelds, set-top boxes, and the bigger smart phones and smart
-cards, are also capable of using Botan. However, Botan uses a
-large amount of code space (up to several megabytes, depending upon
-the compiler and options used), which could be prohibitive in some
-systems. Usage of RAM is modest, usually under 64K.
-
-Botan's design makes it quite easy to remove unused algorithms in such
-a way that applications do not need to be recompiled to work, even
-applications that use the algorithms in question. They can ask Botan
-if the algorithm exists, and if Botan says yes, ask the library to
-give them such an object for that algorithm.
-
-\section{Getting Started}
-
-\subsection{Basic Conventions}
-
-With a very small number of exceptions, declarations in the library
-are contained within the namespace \namespace{Botan}. Botan declares
-several \keyword{typedef}'ed types to help buffer it against changes
-in machine architecture.  These types are used extensively in the
-interface, thus it would be often be convenient to use them without
-the \namespace{Botan} prefix. You can do so by \keyword{using} the
-namespace \namespace{Botan\_types} (this way you can use the type
-names without the namespace prefix, but the remainder of the library
-stays out of the global namespace). The included types are \type{byte}
-and \type{u32bit}, which are unsigned integer types.
-
-The headers for Botan are usually available in the form
-\filename{botan/headername.h}. For brevity in this documentation,
-headers are always just called \filename{headername.h}, but they
-should be used with the \filename{botan/} prefix in your actual code.
-
-\subsection{Initializing the Library}
-
-There is a set of core services that the library needs access to while
-it is performing requests. To ensure these are set up, you must create
-a \type{LibraryInitializer} object (usually called 'init' in Botan
-example code; 'botan\_library' or 'botan\_init' may make more sense in
-real applications) prior to making any calls to Botan. This object's
-lifetime must exceed that of all other Botan objects your application
-creates; for this reason the best place to create the
-\type{LibraryInitializer} is at the start of your \function{main}
-function, since this guarantees that it will be created first and
-destroyed last (via standard C++ RAII rules). The initializer does
-things like setting up the memory allocation system and algorithm
-lookup tables, finding out if there is a high resolution timer
-available to use, and similar such matters. With no arguments, the
-library is initialized with various default settings. So (unless you
-are writing threaded code; see below), all you need is:
-
-\texttt{Botan::LibraryInitializer init;}
-
-at the start of your \texttt{main}.
-
-The constructor takes an optional string that specifies arguments.
-Currently the only possible argument is ``thread\_safe'', which must
-have an boolean argument (for instance ``thread\_safe=false'' or
-``thread\_safe=true''). If ``thread\_safe'' is specified as true the
-library will attempt to register a mutex type to properly guard access
-to shared resources. However these locks do not protect individual
-Botan objects: explicit locking must be used if you wish to share a
-single object between threads.
-
-If you do not create a \type{LibraryInitializer} object, all library
-operations will fail, because it will be unable to do basic things
-like allocate memory or get random bits. You should never create more
-than one \type{LibraryInitializer}.
-
-It is not strictly necessary to create a \type{LibraryInitializer};
-the actual code performing the initialization and shutdown are in
-static member functions of \type{LibraryInitializer}, called
-\function{initialize} and \function{deinitialize}. A
-\type{LibraryInitializer} merely provides a convenient RAII wrapper
-for the operations (thus for the internal library state as well).
-
-\subsection{Pitfalls}
-
-There are a few things to watch out for to prevent problems when using Botan.
-
-Never allocate any kind of Botan object globally. The problem with
-doing this is that the constructor for such an object will be called
-before the library is initialized. Many Botan objects will, in their
-constructor, make one or more calls into the library global state
-object. Access to this object is checked, so an exception should be
-thrown (rather than a memory access violation or undetected
-uninitialized object access). A rough equivalent that will work is to
-keep a global pointer to the object, initializing it after creating
-your \type{LibraryInitializer}. Merely making the
-\type{LibraryInitializer} also global will probably not help, because
-C++ does not make very strong guarantees about the order that such
-objects will be created.
-
-The same rule applies for making sure the destructors of all your
-Botan objects are called before the \type{LibraryInitializer} is
-destroyed. This implies you can't have static variables that are Botan
-objects inside functions or classes; in many C++ runtimes, these
-objects will be destroyed after main has returned.
-
-Botan's memory object classes (\type{MemoryRegion},
-\type{MemoryVector}, \type{SecureVector}) are extremely primitive, and
-meant only for secure storage of potentially sensitive data like
-keys. They do not meet the requirements for an STL container object
-and you should not try to use them with STL algorithms. For a
-general-purpose container, use \type{std::vector}.
-
-Use a \function{try}/\function{catch} block inside your
-\function{main} function, and catch any \type{std::exception} throws
-(remember to catch by reference, as \type{std::exception}'s
-\function{what} method is polymorphic). This is not strictly required,
-but if you don't, and Botan throws an exception, the runtime will call
-\function{std::terminate}, which usually calls \function{abort} or
-something like it, leaving you (or worse, a user of your application)
-wondering what went wrong.
-
-\subsection{Information Flow: Pipes and Filters}
-
-Many common uses of cryptography involve processing one or more
-streams of data. Botan provides services that make setting up data
-flows through various operations, such as compression, encryption, and
-base64 encoding. Each of these operations is implemented in what are
-called \emph{filters} in Botan. A set of filters are created and
-placed into a \emph{pipe}, and information ``flows'' through the pipe
-until it reaches the end, where the output is collected for
-retrieval. If you're familiar with the Unix shell environment, this
-design will sound quite familiar.
-
-Here is an example that uses a pipe to base64 encode some strings:
-
-\begin{verbatim}
-  Pipe pipe(new Base64_Encoder); // pipe owns the pointer
-  pipe.start_msg();
-  pipe.write(``message 1'');
-  pipe.end_msg(); // flushes buffers, increments message number
-
-  // process_msg(x) is start_msg() && write(x) && end_msg()
-  pipe.process_msg(``message2'');
-
-  std::string m1 = pipe.read_all_as_string(0); // ``message1''
-  std::string m2 = pipe.read_all_as_string(1); // ``message2''
-\end{verbatim}
-
-Bytestreams in the pipe are grouped into messages; blocks of data that
-are processed in an identical fashion (\ie, with the same sequence of
-\type{Filter}s). Messages are delimited by calls to
-\function{start\_msg} and \function{end\_msg}. Each message in a pipe
-has its own identifier, which currently is an integer that increments
-up from zero.
-
-As you can see, the \type{Base64\_Encoder} was allocated using
-\keyword{new}; but where was it deallocated? When a filter object is
-passed to a \type{Pipe}, the pipe takes ownership of the object, and
-will deallocate it when it is no longer needed.
-
-There are two different ways to make use of messages. One is to send
-several messages through a \type{Pipe} without changing the
-\type{Pipe}'s configuration, so you end up with a sequence of
-messages; one use of this would be to send a sequence of identically
-encrypted UDP packets, for example (note that the \emph{data} need not
-be identical; it is just that each is encrypted, encoded, signed, etc
-in an identical fashion). Another is to change the filters that are
-used in the \type{Pipe} between each message, by adding or removing
-\type{Filter}s; functions that let you do this are documented in the
-Pipe API section.
-
-Botan has about 40 filters that perform different operations on data.
-Here's code that uses one of them to encrypt a string with AES:
-
-\begin{verbatim}
-  AutoSeeded_RNG rng,
-  SymmetricKey key(rng, 16); // a random 128-bit key
-  InitializationVector iv(rng, 16); // a random 128-bit IV
-
-  // The algorithm we want is specified by a string
-  Pipe pipe(get_cipher(``AES-128/CBC'', key, iv, ENCRYPTION));
-
-  pipe.process_msg(``secrets'');
-  pipe.process_msg(``more secrets'');
-
-  MemoryVector<byte> c1 = pipe.read_all(0);
-
-  byte c2[4096] = { 0 };
-  u32bit got_out = pipe.read(c2, sizeof(c2), 1);
-  // use c2[0...got_out]
-\end{verbatim}
-
-Note the use of \type{AutoSeeded\_RNG}, which is a random number
-generator. If you want to, you can explicitly set up the random number
-generators and entropy sources you want to, however for 99\% of cases
-\type{AutoSeeded\_RNG} is preferable.
-
-\type{Pipe} also has convenience methods for dealing with
-\type{std::iostream}s. Here is an example of those, using the
-\type{Bzip\_Compression} filter (included as a module; if you have
-bzlib available, check \filename{building.pdf} for how to enable it)
-to compress a file:
-
-\begin{verbatim}
-  std::ifstream in(``data.bin'', std::ios::binary)
-  std::ofstream out(``data.bin.bz2'', std::ios::binary)
-
-  Pipe pipe(new Bzip_Compression);
-
-  pipe.start_msg();
-  in >> pipe;
-  pipe.end_msg();
-  out << pipe;
-\end{verbatim}
-
-However there is a hitch to the code above; the complete contents of
-the compressed data will be held in memory until the entire message
-has been compressed, at which time the statement \verb|out << pipe| is
-executed, and the data is freed as it is read from the pipe and
-written to the file. But if the file is very large, we might not have
-enough physical memory (or even enough virtual memory!) for that to be
-practical. So instead of storing the compressed data in the pipe for
-reading it out later, we divert it directly to the file:
-
-\begin{verbatim}
-  std::ifstream in(``data.bin'', std::ios::binary)
-  std::ofstream out(``data.bin.bz2'', std::ios::binary)
-
-  Pipe pipe(new Bzip_Compression, new DataSink_Stream(out));
-
-  pipe.start_msg();
-  in >> pipe;
-  pipe.end_msg();
-\end{verbatim}
-
-This is the first code we've seen so far that uses more than one
-filter in a pipe. The output of the compressor is sent to the
-\type{DataSink\_Stream}. Anything written to a \type{DataSink\_Stream}
-is written to a file; the filter produces no output. As soon as the
-compression algorithm finishes up a block of data, it will send it along,
-at which point it will immediately be written to disk; if you were to
-call \verb|pipe.read_all()| after \verb|pipe.end_msg()|, you'd get an
-empty vector out.
-
-Here's an example using two computational filters:
-
-\begin{verbatim}
-  AutoSeeded_RNG rng,
-   SymmetricKey key(rng, 32);
-   InitializationVector iv(rng, 16);
-
-   Pipe encryptor(get_cipher("AES/CBC/PKCS7", key, iv, ENCRYPTION),
-                  new Base64_Encoder);
-
-   encryptor.start_msg();
-   file >> encryptor;
-   encryptor.end_msg(); // flush buffers, complete computations
-   std::cout << encryptor;
-\end{verbatim}
-
-\subsection{Fork}
-
-It is common that you might receive some data and want to
-perform more than one operation on it (\ie, encrypt it with Serpent
-and calculate the SHA-256 hash of the plaintext at the same
-time). That's where \type{Fork} comes in. \type{Fork} is a filter that
-takes input and passes it on to \emph{one or more} \type{Filter}s
-that are attached to it. \type{Fork} changes the nature of the pipe
-system completely. Instead of being a linked list, it becomes a tree.
-
-Each \type{Filter} in the fork is given its own output buffer, and
-thus its own message. For example, if you had previously written two
-messages into a \type{Pipe}, then you start a new one with a
-\type{Fork} that has three paths of \type{Filter}'s inside it, you
-add three new messages to the \type{Pipe}. The data you put into the
-\type{Pipe} is duplicated and sent into each set of \type{Filter}s,
-and the eventual output is placed into a dedicated message slot in the
-\type{Pipe}.
-
-Messages in the \type{Pipe} are allocated in a depth-first manner. This is only
-interesting if you are using more than one \type{Fork} in a single \type{Pipe}.
-As an example, consider the following:
-
-\begin{verbatim}
-   Pipe pipe(new Fork(
-                new Fork(
-                   new Base64_Encoder,
-                   new Fork(
-                      NULL,
-                      new Base64_Encoder
-                      )
-                   ),
-                new Hex_Encoder
-                )
-      );
-\end{verbatim}
-
-In this case, message 0 will be the output of the first \type{Base64\_Encoder},
-message 1 will be a copy of the input (see below for how \type{Fork} interprets
-NULL pointers), message 2 will be the output of the second
-\type{Base64\_Encoder}, and message 3 will be the output of the
-\type{Hex\_Encoder}. As you can see, this results in message numbers being
-allocated in a top to bottom fashion, when looked at on the screen. However,
-note that there could be potential for bugs if this is not anticipated. For
-example, if your code is passed a \type{Filter}, and you assume it is a
-``normal'' one that only uses one message, your message offsets would be
-wrong, leading to some confusion during output.
-
-If Fork's first argument is a null pointer, but a later argument is
-not, then Fork will feed a copy of its input directly through. Here's
-a case where that is useful:
-
-\begin{verbatim}
-   // have std::string ciphertext, auth_code, key, iv, mac_key;
-
-   Pipe pipe(new Base64_Decoder,
-             get_cipher(``AES-128'', key, iv, DECRYPTION),
-             new Fork(
-                0
-                new MAC_Filter(``HMAC(SHA-1)'', mac_key)
-             )
-      );
-
-   pipe.process_msg(ciphertext);
-   std::string plaintext = pipe.read_all_as_string(0);
-   SecureVector<byte> mac = pipe.read_all(1);
-
-   if(mac != auth_code)
-      error();
-\end{verbatim}
-
-Here we wanted to not only decrypt the message, but send the decrypted
-text through an additional computation, in order to compute the
-authentication code.
-
-Any \type{Filter}s that are attached to the \type{Pipe} after the
-\type{Fork} are implicitly attached onto the first branch created by
-the fork. For example, let's say you created this \type{Pipe}:
-
-\begin{verbatim}
-Pipe pipe(new Fork(new Hash_Filter("MD5"), new Hash_Filter("SHA-1")),
-          new Hex_Encoder);
-\end{verbatim}
-
-And then called \function{start\_msg}, inserted some data, then
-\function{end\_msg}. Then \arg{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 \type{Chain}
-instead.
-
-\subsubsection{Chain}
-
-A \type{Chain} filter creates a chain of \type{Filter}s and
-encapsulates them inside a single filter (itself). This allows a
-sequence of filters to become a single filter, to be passed into or
-out of a function, or to a \type{Fork} constructor.
-
-You can call \type{Chain}'s constructor with up to 4 \type{Filter*}s
-(they will be added in order), or with an array of \type{Filter*}s and
-a \type{u32bit} that tells \type{Chain} how many \type{Filter*}s are
-in the array (again, they will be attached in order). Here's the
-example from the last section, using chain instead of relying on the
-obscure rule that version used.
-
-\begin{verbatim}
-  Pipe pipe(new Fork(
-                new Chain(new Hash_Filter("MD5"), new Hex_Encoder),
-                new Hash_Filter("SHA-1")
-                )
-           );
-\end{verbatim}
-
-\subsection{The Pipe API}
-
-\subsubsection{Initializing Pipe}
-
-By default, \type{Pipe} will do nothing at all; any input placed into
-the \type{Pipe} will be read back unchanged. Obviously, this has
-limited utility, and presumably you want to use one or more
-\type{Filter}s to somehow process the data. First, you can choose a
-set of \type{Filter}s to initialize the \type{Pipe} via the
-constructor. You can pass it either a set of up to 4 \type{Filter*}s,
-or a pre-defined array and a length:
-
-\begin{verbatim}
-   Pipe pipe1(new Filter1(/*args*/), new Filter2(/*args*/),
-              new Filter3(/*args*/), new Filter4(/*args*/));
-   Pipe pipe2(new Filter1(/*args*/), new Filter2(/*args*/));
-
-   Filter* filters[5] = {
-     new Filter1(/*args*/), new Filter2(/*args*/), new Filter3(/*args*/),
-     new Filter4(/*args*/), new Filter5(/*args*/) /* more if desired... */
-   };
-   Pipe pipe3(filters, 5);
-\end{verbatim}
-
-This is by far the most common way to initialize a \type{Pipe}. However,
-occasionally a more flexible initialization strategy is necessary; this is
-supported by 4 member functions: \function{prepend}(\type{Filter*}),
-\function{append}(\type{Filter*}), \function{pop}(), and \function{reset}().
-These functions may only be used while the \type{Pipe} in question is not in
-use; that is, either before calling \function{start\_msg}, or after
-\function{end\_msg} has been called (and no new calls to \function{start\_msg}
-have been made yet).
-
-The function \function{reset}() removes all the \type{Filter}s that
-the \type{Pipe} is currently using~--~it is reset to an initialize,
-``empty'' state.  Any data that is being retained by the \type{Pipe}
-is retained after a \function{reset}(), and \function{reset}() does
-not affect the message numbers (discussed later).
-
-Calling \function{prepend} and \function{append} will either prepend
-or append the passed \type{Filter} object to the list of
-transformations. For example, if you \function{prepend} a
-\type{Filter} implementing encryption, and the \type{Pipe} already had
-a \type{Filter} that hex encoded the input, then the next set of
-input would be first encrypted, then hex encoded. Alternately, if you
-called \function{append}, then the input would be first be hex
-encoded, and then encrypted (which is not terribly useful in this
-particular example).
-
-Finally, calling \function{pop}() will remove the first transformation
-of the \type{Pipe}. Say we had called \function{prepend} to put an
-encryption \type{Filter} into a \type{Pipe}; calling \function{pop}()
-would remove this \type{Filter} and return the \type{Pipe} to its
-state before we called \function{prepend}.
-
-\subsubsection{Giving Data to a Pipe}
-
-Input to a \type{Pipe} is delimited into messages, which can be read from
-independently (\ie, you can read 5 bytes from one message, and then all of
-another message, without either read affecting any other messages). The
-messages are delimited by calls to \function{start\_msg} and
-\function{end\_msg}. In between these two calls, you can write data into a
-\type{Pipe}, and it will be processed by the \type{Filter}(s) that it
-contains. Writes at any other time are invalid, and will result in an
-exception.
-
-As to writing, you can call any of the functions called \function{write}(),
-that can take any of: a \type{byte[]}/\type{u32bit} pair, a
-\type{SecureVector<byte>}, a \type{std::string}, a \type{DataSource\&}, or a
-single \type{byte}.
-
-Sometimes, you may want to do only a single write per message. In this case,
-you can use the \function{process\_msg} series of functions, which start a
-message, write their argument into the \type{Pipe}, and then end the
-message. In this case you would not make any explicit calls to
-\function{start\_msg}/\function{end\_msg}. The version of \function{write}
-that takes a single \type{byte} is not supported by \function{process\_msg},
-but all the other variants are.
-
-\type{Pipe} can also be used with the \verb|>>| operator, and will accept a
-\type{std::istream}, (or on Unix systems with the \verb|fd_unix| module), a
-Unix file descriptor. In either case, the entire contents of the file will be
-read into the \type{Pipe}.
-
-\subsubsection{Getting Output from a Pipe}
-
-Retrieving the processed data from a \type{Pipe} is a bit more complicated, for
-various reasons. In particular, because \type{Pipe} will separate each message
-into a separate buffer, you have to be able to retrieve data from each message
-independently. Each of \type{Pipe}'s read functions has a final parameter that
-specifies what message to read from (as a 32-bit integer). If this parameter is
-set to \type{Pipe::DEFAULT\_MESSAGE}, it will read the current default message
-(\type{DEFAULT\_MESSAGE} is also the default value of this parameter). The
-parameter will not be mentioned in further discussion of the reading API, but
-it is always there (unless otherwise noted).
-
-Reading is done with a variety of functions. The most basic are \type{u32bit}
-\function{read}(\type{byte} \arg{out}[], \type{u32bit} \arg{len}) and
-\type{u32bit} \function{read}(\type{byte\&} \arg{out}). Each reads into
-\arg{out} (either up to \arg{len} bytes, or a single byte for the one taking a
-\type{byte\&}), and returns the total number of bytes read. There is a variant
-of these functions, all named \function{peek}, which performs the same
-operations, but does not remove the bytes from the message (reading is a
-destructive operation with a \type{Pipe}).
-
-There are also the functions \type{SecureVector<byte>} \function{read\_all}(),
-and \type{std::string} \function{read\_all\_as\_string}(), which return the
-entire contents of the message, either as a memory buffer, or a
-\type{std::string} (which is generally only useful if the \type{Pipe} has
-encoded the message into a text string, such as when a \type{Base64\_Encoder}
-is used).
-
-To determine how many bytes are left in a message, call \type{u32bit}
-\function{remaining}() (which can also take an optional message
-number). Finally, there are some functions for managing the default message
-number: \type{u32bit} \function{default\_msg}() will return the current default
-message, \type{u32bit} \function{message\_count}() will return the total number
-of messages (0...\function{message\_count}()-1), and
-\function{set\_default\_msg}(\type{u32bit} \arg{msgno}) will set a new default
-message number (which must be a valid message number for that \type{Pipe}). The
-ability to set the default message number is particularly important in the case
-of using the file output operations (\verb|<<| with a \type{std::ostream} or
-Unix file descriptor), because there is no way to specify it explicitly when
-using the output operator.
-
-\subsection{A Filter Example}
-
-Here is some code that takes one or more filenames in \arg{argv} and
-calculates the result of several hash functions for each file. The complete
-program can be found as \filename{hasher.cpp} in the Botan distribution. For
-brevity, error checking has been removed.
-
-\begin{verbatim}
-   string name[3] = { "MD5", "SHA-1", "RIPEMD-160" };
-   Botan::Filter* hash[3] = {
-      new Botan::Chain(new Botan::Hash_Filter(name[0]),
-                        new Botan::Hex_Encoder),
-      new Botan::Chain(new Botan::Hash_Filter(name[1]),
-                        new Botan::Hex_Encoder),
-      new Botan::Chain(new Botan::Hash_Filter(name[2]),
-                        new Botan::Hex_Encoder) };
-
-   Botan::Pipe pipe(new Botan::Fork(hash, COUNT));
-
-   for(u32bit j = 1; argv[j] != 0; j++)
-      {
-      ifstream file(argv[j]);
-      pipe.start_msg();
-      file >> pipe;
-      pipe.end_msg();
-      file.close();
-      for(u32bit k = 0; k != 3; k++)
-         {
-         pipe.set_default_msg(3*(j-1)+k);
-         cout << name[k] << "(" << argv[j] << ") = " << pipe << endl;
-         }
-      }
-\end{verbatim}
-
-
-\subsection{Filter Catalog}
-
-This section contains descriptions of every \type{Filter} included in
-the portable sections of Botan. \type{Filter}s provided by modules
-are documented elsewhere.
-
-\subsubsection{Keyed Filters}
-
-A few sections ago, it was mentioned that \type{Pipe} can process multiple
-messages, treating each of them the same. Well, that was a bit of a
-lie. There are some algorithms (in particular, block ciphers not in ECB mode,
-and all stream ciphers) that change their state as data is put through them.
-
-Naturally, you might well want to reset the keys or (in the case of block
-cipher modes) IVs used by such filters, so multiple messages can be processed
-using completely different keys, or new IVs, or new keys and IVs, or whatever.
-And in fact, even for a MAC or an ECB block cipher, you might well want to
-change the key used from message to message.
-
-Enter \type{Keyed\_Filter}, which acts as an abstract interface for
-any filter that is uses keys: block cipher modes, stream ciphers,
-MACs, and so on. It has two functions, \function{set\_key} and
-\function{set\_iv}. Calling \function{set\_key} will, naturally, set
-(or reset) the key used by the algorithm. Setting the IV only makes
-sense in certain algorithms -- a call to \function{set\_iv} on an
-object that doesn't support IVs will be ignored. You \emph{must} call
-\function{set\_key} before calling \function{set\_iv}: while not all
-\type{Keyed\_Filter} objects require this, you should assume it is
-required anytime you are using a \type{Keyed\_Filter}.
-
-Here's a example:
-
-\begin{verbatim}
-   Keyed_Filter *cast, *hmac;
-   Pipe pipe(new Base64_Decoder,
-             // Note the assignments to the cast and hmac variables
-             cast = new CBC_Decryption("CAST-128", "PKCS7", cast_key, iv),
-             new Fork(
-                0, // Read the section 'Fork' to understand this
-                new Chain(
-                   hmac = new MAC_Filter("HMAC(SHA-1)", mac_key, 12),
-                   new Base64_Encoder
-                   )
-                )
-      );
-   pipe.start_msg();
-   [use pipe for a while, decrypt some stuff, derive new keys and IVs]
-   pipe.end_msg();
-
-   cast->set_key(cast_key2);
-   cast->set_iv(iv2);
-   hmac->set_key(mac_key2);
-
-   pipe.start_msg();
-   [use pipe for some other things]
-   pipe.end_msg();
-\end{verbatim}
-
-There are some requirements to using \type{Keyed\_Filter} that you must
-follow. If you call \function{set\_key} or \function{set\_iv} on a filter that
-is owned by a \type{Pipe}, you must do so while the \type{Pipe} is
-``unlocked''. This refers to the times when no messages are being processed by
-\type{Pipe} -- either before \type{Pipe}'s \function{start\_msg} is called, or
-after \function{end\_msg} is called (and no new call to \function{start\_msg}
-has happened yet). Doing otherwise will result in undefined behavior, probably
-silently getting invalid output.
-
-And remember: if you're resetting both values, reset the key \emph{first}.
-
-\subsubsection{Cipher Filters}
-
-Getting a hold of a \type{Filter} implementing a cipher is very
-easy. Make sure you're including the header \filename{lookup.h}, and
-then call \function{get\_cipher}. You will pass the return value
-directly into a \type{Pipe}. There are a couple different functions
-which do varying levels of initialization:
-
-\function{get\_cipher}(\type{std::string} \arg{cipher\_spec},
-                       \type{SymmetricKey} \arg{key},
-                       \type{InitializationVector} \arg{iv},
-                       \type{Cipher\_Dir} \arg{dir});
-
-\function{get\_cipher}(\type{std::string} \arg{cipher\_spec},
-                       \type{SymmetricKey} \arg{key},
-                       \type{Cipher\_Dir} \arg{dir});
-
-The version that doesn't take an IV is useful for things that don't
-use them, like block ciphers in ECB mode, or most stream ciphers. If
-you specify a \arg{cipher\_spec} that does want a IV, and you use the
-version that doesn't take one, an exception will be thrown. The
-\arg{dir} argument can be either \type{ENCRYPTION} or
-\type{DECRYPTION}.
-
-The \arg{cipher\_spec} is a string that specifies what cipher is to be
-used. The general syntax for \arg{cipher\_spec} is ``STREAM\_CIPHER'',
-``BLOCK\_CIPHER/MODE'', or ``BLOCK\_CIPHER/MODE/PADDING''. In the case
-of stream ciphers, no mode is necessary, so just the name is
-sufficient. A block cipher requires a mode of some sort, which can be
-``ECB'', ``CBC'', ``CFB(n)'', ``OFB'', ``CTR-BE'', or ``EAX(n)''. The
-argument to CFB mode is how many bits of feedback should be used. If
-you just use ``CFB'' with no argument, it will default to using a
-feedback equal to the block size of the cipher. EAX mode also takes an
-optional bit argument, which tells EAX how large a tag size to
-use~--~generally this is the size of the block size of the cipher,
-which is the default if you don't specify any argument.
-
-In the case of the ECB and CBC modes, a padding method can also be
-specified. If it is not supplied, ECB defaults to not padding, and CBC
-defaults to using PKCS \#5/\#7 compatible padding. The padding methods
-currently available are ``NoPadding'', ``PKCS7'', ``OneAndZeros'', and
-``CTS''. CTS padding is currently only available for CBC mode, but the
-others can also be used in ECB mode.
-
-Some example \arg{cipher\_spec} arguments are: ``AES-128/CBC'',
-``Blowfish/CTR-BE'', ``Serpent/XTS'', and ``AES-256/EAX''.
-
-``CTR-BE'' refers to counter mode where the counter is incremented as
-if it were a big-endian encoded integer. This is compatible with most
-other implementations, but it is possible some will use the
-incompatible little endian convention. This version would be denoted
-as ``CTR-LE'' if it were supported.
-
-``EAX'' is a new cipher mode designed by Wagner, Rogaway, and
-Bellare. It is an authenticated cipher mode (that is, no separate
-authentication is needed), has provable security, and is free from
-patent entanglements. It runs about half as fast as most of the other
-cipher modes (like CBC, OFB, or CTR), which is not bad considering you
-don't need to use an authentication code.
-
-\subsubsection{Hashes and MACs}
-
-Hash functions and MACs don't need anything special when it comes to
-filters. Both just take their input and produce no output until
-\function{end\_msg()} is called, at which time they complete the hash or MAC
-and send that as output.
-
-These \type{Filter}s take a string naming the type to be used. If for some
-reason you name something that doesn't exist, an exception will be thrown.
-
-\noindent
-\function{Hash\_Filter}(\type{std::string} \arg{hash},
-                        \type{u32bit} \arg{outlength}):
-
-This type hashes its input with \arg{hash}. When \function{end\_msg} is called
-on the owning \type{Pipe}, the hash is completed and the digest is sent on to
-the next thing in the pipe. The argument \arg{outlength} specifies how much of
-the output of the hash will be passed along to the next filter when
-\function{end\_msg} is called. By default, it will pass the entire hash.
-
-Examples of names for \function{Hash\_Filter} are ``SHA-1'' and ``Whirlpool''.
-
-\noindent
-\function{MAC\_Filter}(\type{std::string} \arg{mac},
-                       \type{const SymmetricKey\&} \arg{key},
-                       \type{u32bit} \arg{outlength}):
-
-The constructor for a \type{MAC\_Filter} takes a key, used in calculating the
-MAC, and a length parameter, which has semantics the same as the one
-passed to \type{Hash\_Filter}s constructor.
-
-Examples for \arg{mac} are ``HMAC(SHA-1)'', ``CMAC(AES-128)'', and the
-exceptionally long, strange, and probably useless name
-``CMAC(Lion(Tiger(20,3),MARK-4,1024))''.
-
-\subsubsection{PK Filters}
-
-There are four classes in this category, \type{PK\_Encryptor\_Filter},
-\type{PK\_Decryptor\_Filter}, \type{PK\_Signer\_Filter}, and
-\type{PK\_Verifier\_Filter}. Each takes a pointer to an object of the
-appropriate type (\type{PK\_Encryptor}, \type{PK\_Decryptor}, etc) that is
-deleted by the destructor. These classes are found in \filename{pk\_filts.h}.
-
-Three of these, for encryption, decryption, and signing are much the
-same in terms of dataflow - ach of them buffers its input until the
-end of the message is marked with a call to the \function{end\_msg}
-function. Then they encrypt, decrypt, or sign the entire input as a
-single blob and send the output (the ciphertext, the plaintext, or the
-signature) into the next filter.
-
-Signature verification works a little differently, because it needs to
-know what the signature is in order to check it. You can either pass
-this in along with the constructor, or call the function
-\function{set\_signature} -- with this second method, you need to keep
-a pointer to the filter around so you can send it this command. In
-either case, after \function{end\_msg} is called, it will try to
-verify the signature (if the signature has not been set by either
-method, an exception will be thrown here). It will then send a single
-byte onto the next filter -- a 1 or a 0, which specifies whether the
-signature verified or not (respectively).
-
-For more information about PK algorithms (including creating the
-appropriate objects to pass to the constructors), read the section
-``Public Key Cryptography'' in this manual.
-
-\subsubsection{Encoders}
-
-Often you want your data to be in some form of text (for sending over channels
-that aren't 8-bit clean, printing it, etc). The filters \type{Hex\_Encoder}
-and \type{Base64\_Encoder} will convert arbitrary binary data into hex or
-base64 formats. Not surprisingly, you can use \type{Hex\_Decoder} and
-\type{Base64\_Decoder} to convert it back into its original form.
-
-Both of the encoders can take a few options about how the data should be
-formatted (all of which have defaults). The first is a \type{bool} which
-says if the encoder should insert line breaks. This defaults to
-false. Line breaks don't matter either way to the decoder, but it makes the
-output a bit more appealing to the human eye, and a few transport mechanisms
-(notably some email systems) limit the maximum line length.
-
-The second encoder option is an integer specifying how long such lines will be
-(obviously this will be ignored if line-breaking isn't being used). The default
-tends to be in the range of 60-80 characters, but is not specified. If
-you want a specific value, set it. Otherwise the default should be fine.
-
-Lastly, \type{Hex\_Encoder} takes an argument of type \type{Case}, which can be
-\type{Uppercase} or \type{Lowercase} (default is \type{Uppercase}). This
-specifies what case the characters A-F should be output as. The base64 encoder
-has no such option, because it uses both upper and lower case letters for its
-output.
-
-The decoders both take a single option, which tells it how the object
-should behave in the case of invalid input. The enum (called
-\type{Decoder\_Checking}) can take on any of three values:
-\type{NONE}, \type{IGNORE\_WS}, and \type{FULL\_CHECK}. With
-\type{NONE} (the default, for compatibility with previous releases),
-invalid input (for example, a ``z'' character in supposedly hex input)
-will be ignored. With \type{IGNORE\_WS}, whitespace will be ignored by
-the decoder, but receiving other non-valid data will raise an
-exception. Finally, \type{FULL\_CHECK} will raise an exception for
-\emph{any} characters not in the encoded character set, including
-whitespace.
-
-You can find the declarations for these types in \filename{hex.h} and
-\filename{base64.h}.
-
-\subsection{Rolling Your Own}
-
-The system of filters and pipes was designed in an attempt to make it
-as simple as possible to write new \type{Filter} objects. There are
-four functions that need to be implemented by an object deriving from
-\type{Filter}:
-
-\noindent
-\type{void} \function{write}(\type{byte} \arg{input}[], \type{u32bit}
-\arg{length}):
-
-The \function{write} function is what is called when a filter receives input
-for it to process. The filter is \emph{not} required to process it right away;
-many filters buffer their input before producing any output. A filter will
-usually have \function{write} called many times during its lifetime.
-
-\noindent
-\type{void} \function{send}(\type{byte} \arg{output}[], \type{u32bit}
-\arg{length}):
-
-Eventually, a filter will want to produce some output to send along to the next
-filter in the pipeline. It does so by calling \function{send} with whatever it
-wants to send along to the next filter. There is also a version of
-\function{send} taking a single byte argument, as a convenience.
-
-\noindent
-\type{void} \function{start\_msg()}:
-
-This function is optional. Implement it if your \type{Filter} would like to do
-some processing or setup at the start of each message (for an example, see the
-Zlib compression module).
-
-\noindent
-\type{void} \function{end\_msg()}:
-
-Implementing the \function{end\_msg} function is optional. It is
-called when it has been requested that filters finish up their
-computations. The filter should finish up with whatever computation it
-is working on (for example, a compressing filter would flush the
-compressor and \function{send} the final block), and empty any buffers
-in preparation for processing a fresh new set of input.
-
-Additionally, if necessary, filters can define a constructor that
-takes any needed arguments, and a destructor to deal with deallocating
-memory, closing files, etc.
-
-\section{Public Key Cryptography}
-
-Let's create a 1024-bit RSA private key, encode the public key as a
-PKCS \#1 file with PEM encoding (which can be understood by many other
-cryptographic programs)
-
-\begin{verbatim}
-// everyone does:
-AutoSeeded_RNG rng;
-
-// Alice
-RSA_PrivateKey priv_rsa(rng, 1024 /* bits */);
-
-std::string alice_pem = X509::PEM_encode(priv_rsa);
-
-// send alice_pem to Bob, who does
-
-// Bob
-std::auto_ptr<Public_Key> alice(load_key(alice_pem));
-
-RSA_PublicKey* alice_rsa = dynamic_cast<RSA_PublicKey>(alice);
-if(alice_rsa)
-   {
-   /* ... */
-   }
-
-\end{verbatim}
-
-\subsection{Creating PK Algorithm Key Objects}
-
-The library has interfaces for encryption, signatures, etc that do not require
-knowing the exact algorithm in use (for example RSA and Rabin-Williams
-signatures are handled by the exact same code path).
-
-One place where we \emph{do} need to know exactly what kind of
-algorithm is in use is when we are creating a key (\emph{But}: read
-the section ``Importing and Exporting PK Keys'', later in this
-manual).
-
-There are currently three kinds of public key algorithms in Botan:
-ones based on integer factorization (RSA and Rabin-Williams), ones
-based on the discrete logarithm problem in the integers modulo a prime
-(DSA, Diffie-Hellman, Nyberg-Rueppel, and ElGamal), and ones based on
-the discrete logarithm problem in an elliptic curve (ECDSA, ECDH, GOST
-34.10). The systems based on discrete logarithms (in either regular
-integers or elliptic curves) use a group (a mathematical term), which
-can be shared among many keys. An elliptic curve group is represented
-by the class \type{EC\_Domain\_Params}, while a modulo-prime group is
-represented by a \type{DL\_Group}.
-
-There are two ways to create a DL private key (such as
-\type{DSA\_PrivateKey}). One is to pass in just a \type{DL\_Group}
-object -- a new key will automatically be generated. The other
-involves passing in a group to use, along with both the public and
-private values (private value first).
-
-Since in integer factorization algorithms, the modulus used isn't shared by
-other keys, we don't use this notion. You can create a new key by passing in a
-\type{u32bit} telling how long (in bits) the key should be, or you can copy an
-pre-existing key by passing in the appropriate parameters (primes, exponents,
-etc). For RSA and Rabin-Williams (the two IF schemes in Botan), the parameters
-are all \type{BigInt}s: prime 1, prime 2, encryption exponent, decryption
-exponent, modulus. The last two are optional, since they can easily be derived
-from the first three.
-
-\subsubsection{Creating a DL\_Group}
-
-There are quite a few ways to get a \type{DL\_Group} object. The best is to use
-the function \function{get\_dl\_group}, which takes a string naming a group; it
-will either return that group, if it knows about it, or throw an
-exception. Names it knows about include ``IETF-n'' where n is 768, 1024, 1536,
-2048, 3072, or 4096, and ``DSA-n'', where n is 512, 768, or 1024. The IETF
-groups are the ones specified for use with IPSec, and the DSA ones are the
-default DSA parameters specified by Java's JCE. For DSA and Nyberg-Rueppel, you
-should only use the ``DSA-n'' groups, while Diffie-Hellman and ElGamal can use
-either type (keep in mind that some applications/standards require DH/ELG to
-use DSA-style primes, while others require strong prime groups).
-
-You can also generate a new random group. This is not recommend, because it is
-quite slow, especially for safe primes.
-
-\subsection{Key Checking}
-
-Most public key algorithms have limitations or restrictions on their
-parameters. For example RSA requires an odd exponent, and algorithms based on
-the discrete logarithm problem need a generator $> 1$.
-
-Each low-level public key type has a function named \function{check\_key} that
-takes a \type{bool}. This function returns a Boolean value that declares
-whether or not the key is valid (from an algorithmic standpoint). For example,
-it will check to make sure that the prime parameters of a DSA key are, in fact,
-prime. It does not have anything to do with the validity of the key for any
-particular use, nor does it have anything to do with certificates that link a
-key (which, after all, is just some numbers) with a user or other entity. If
-\function{check\_key}'s argument is \type{true}, then it does ``strong''
-checking, which includes expensive operations like primality checking.
-
-Keys are always checked when they are loaded or generated, so typically there
-is no reason to use this function directly. However, you can disable or reduce
-the checks for particular cases (public keys, loaded private keys, generated
-private keys) by setting the right config toggle (see the section on the
-configuration subsystem for details).
-
-\subsection{Getting a PK algorithm object}
-
-The key types, like \type{RSA\_PrivateKey}, do not implement any kind
-of padding or encoding (which is necessary for security). To get an
-object that knows how to do padding, use the wrapper classes included
-in \filename{pubkey.h}. These take a key, along with a string that
-specifies what hashing and encoding method(s) to use. Examples of such
-strings are ``EME1(SHA-256)'' for OAEP encryption and
-``EMSA4(SHA-256)'' for PSS signatures (where the message is hashed
-using SHA-256).
-
-Here are some basic examples (using an RSA key) to give you a feel for
-the possibilities. These examples assume \type{rsakey} is an
-\type{RSA\_PrivateKey}, since otherwise we would not be able to create
-a decryption or signature object with it (you can create encryption or
-signature verification objects with public keys, naturally).
-
-\begin{verbatim}
-   // PKCS #1 v2.0 / IEEE 1363 compatible encryption
-   PK_Encryptor_EME rsa_enc_pkcs1_v2(rsakey, "EME1(SHA-1)");
-   // PKCS #1 v1.5 compatible encryption
-   PK_Encryptor_EME rsa_enc_pkcs1_v15(rsakey, "PKCS1v15")
-
-   // This object can decrypt things encrypted by rsa_
-   PK_Decryptor_EME rsa_dec_pkcs1_v2(rsakey, "EME1(SHA-1)");
-
-   // PKCS #1 v1.5 compatible signatures
-   PK_Signer rsa_sign_pkcs1_v15(rsakey, "EMSA3(MD5)");
-   PK_Verifier rsa_verify_pkcs1_v15(rsakey, "EMSA3(MD5)");
-
-   // PKCS #1 v2.1 compatible signatures
-   PK_Signer rsa_sign_pkcs1_v2(rsakey, "EMSA4(SHA-1)");
-   PK_Verifier rsa_verify_pkcs1_v2(rsakey, "EMSA4(SHA-1)");
-\end{verbatim}
-
-\subsection{Encryption}
-
-The \type{PK\_Encryptor} and \type{PK\_Decryptor} classes are the
-interface for encryption and decryption, respectively.
-
-Calling \function{encrypt} with a \type{byte} array, a length
-parameter, and an RNG object will return the input encrypted with
-whatever scheme is being used. Calling the similar \function{decrypt}
-will perform the inverse operation. You can also do these operations
-with \type{SecureVector<byte>}s. In all cases, the output is returned
-via a \type{SecureVector<byte>}.
-
-If you attempt an operation with a larger size than the key can
-support (this limit varies based on the algorithm, the key size, and
-the padding method used (if any)), an exception will be thrown. You
-can call \function{maximum\_input\_size} to find out the maximum size
-input (in bytes) that you can safely use with any particular key.
-
-Available public key encryption algorithms in Botan are RSA and
-ElGamal. The encoding methods are EME1, denoted by ``EME1(HASHNAME)'',
-PKCS \#1 v1.5, called ``PKCS1v15'' or ``EME-PKCS1-v1\_5'', and raw
-encoding (``Raw'').
-
-For compatibility reasons, PKCS \#1 v1.5 is recommend for use with
-ElGamal (most other implementations of ElGamal do not support any
-other encoding format). RSA can also be used with PKCS \# 1 encoding,
-but because of various possible attacks, EME1 is the preferred
-encoding. EME1 requires the use of a hash function: unless a competent
-applied cryptographer tells you otherwise, you should use SHA-256 or
-SHA-512.
-
-Don't use ``Raw'' encoding unless you need it for backward
-compatibility with old protocols. There are many possible attacks
-against both ElGamal and RSA when they are used in this way.
-
-\subsection{Signatures}
-
-The signature algorithms look quite a bit like the hash functions. You
-can repeatedly call \function{update}, giving more and more of a
-message you wish to sign, and then call \function{signature}, which
-will return a signature for that message. If you want to do it all in
-one shot, call \function{sign\_message}, which will just call
-\function{update} with its argument and then return whatever
-\function{signature} returns. Generating a signature requires random
-numbers with some schemes, so \function{signature} and
-\function{sign\_message} both take a \type{RandomNumberGenerator\&}.
-
-You can validate a signature by updating the verifier class, and finally seeing
-the if the value returned from \function{check\_signature} is true (you pass
-the supposed signature to the \function{check\_signature} function as a byte
-array and a length or as a \type{MemoryRegion<byte>}). There is another
-function, \function{verify\_message}, which takes a pair of byte array/length
-pairs (or a pair of \type{MemoryRegion<byte>} objects), the first of which is
-the message, the second being the (supposed) signature. It returns true if the
-signature is valid and false otherwise.
-
-Available public key signature algorithms in Botan are RSA, DSA,
-ECDSA, GOST-34.11, Nyberg-Rueppel, and Rabin-Williams. Signature
-encoding methods include EMSA1, EMSA2, EMSA3, EMSA4, and Raw. All of
-them, except Raw, take a parameter naming a message digest function to
-hash the message with. The Raw encoding signs the input directly; if
-the message is too big, the signing operation will fail. Raw is not
-useful except in very specialized applications.
-
-There are various interactions that make certain encoding schemes and
-signing algorithms more or less useful.
-
-EMSA2 is the usual method for encoding Rabin-William signatures, so
-for compatibility with other implementations you may have to use
-that. EMSA4 (also called PSS), also works with Rabin-Williams. EMSA1
-and EMSA3 do \emph{not} work with Rabin-Williams.
-
-RSA can be used with any of the available encoding methods. EMSA4 is
-by far the most secure, but is not (as of now) widely
-implemented. EMSA3 (also called ``EMSA-PKCS1-v1\_5'') is commonly used
-with RSA (for example in SSL). EMSA1 signs the message digest
-directly, without any extra padding or encoding. This may be useful,
-but is not as secure as either EMSA3 or EMSA4. EMSA2 may be used but
-is not recommended.
-
-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.
-
-\subsection{Key Agreement}
-
-You can get a hold of a \type{PK\_Key\_Agreement\_Scheme} object by
-calling \function{get\_pk\_kas} with a key that is of a type that
-supports key agreement (such as a Diffie-Hellman key stored in a
-\type{DH\_PrivateKey} object), and the name of a key derivation
-function. This can be ``Raw'', meaning the output of the primitive
-itself is returned as the key, or ``KDF1(hash)'' or ``KDF2(hash)''
-where ``hash'' is any string you happen to like (hopefully you like
-strings like ``SHA-256'' or ``RIPEMD-160''), or
-``X9.42-PRF(keywrap)'', which uses the PRF specified in ANSI X9.42. It
-takes the name or OID of the key wrap algorithm that will be used to
-encrypt a content encryption key.
-
-How key agreement works is that you trade public values with some
-other party, and then each of you runs a computation with the other's
-value and your key (this should return the same result to both
-parties). This computation can be called by using
-\function{derive\_key} with either a byte array/length pair, or a
-\type{SecureVector<byte>} than holds the public value of the other
-party. The last argument to either call is a number that specifies how
-long a key you want.
-
-Depending on the KDF you're using, you \emph{might not} get back a key
-of the size you requested. In particular ``Raw'' will return a number
-about the size of the Diffie-Hellman modulus, and KDF1 can only return
-a key that is the same size as the output of the hash. KDF2, on the
-other hand, will always give you a key exactly as long as you request,
-regardless of the underlying hash used with it. The key returned is a
-\type{SymmetricKey}, ready to pass to a block cipher, MAC, or other
-symmetric algorithm.
-
-The public value that should be used can be obtained by calling
-\function{public\_data}, which exists for any key that is associated with a
-key agreement algorithm. It returns a \type{SecureVector<byte>}.
-
-``KDF2(SHA-256)'' is by far the preferred algorithm for key derivation
-in new applications. The X9.42 algorithm may be useful in some
-circumstances, but unless you need X9.42 compatibility, KDF2 is easier
-to use.
-
-There is a Diffie-Hellman example included in the distribution, which you may
-want to examine.
-
-\subsection{Importing and Exporting PK Keys}
-
-[This section mentions \type{Pipe} and \type{DataSource}, which is not covered
-until later in the manual. Please read those sections for more about
-\type{Pipe} and \type{DataSource} and their uses.]
-
-There are many, many different (often conflicting) standards surrounding public
-key cryptography. There is, thankfully, only two major standards surrounding
-the representation of a public or private key: X.509 (for public keys), and
-PKCS \#8 (for private keys). Other crypto libraries, like OpenSSL and B-SAFE,
-also support these formats, so you can easily exchange keys with software that
-doesn't use Botan.
-
-In addition to ``plain'' public keys, Botan also supports X.509 certificates.
-These are documented in the section ``Certificate Handling'', later in this
-manual.
-
-\subsubsection{Public Keys}
-
-The interfaces for doing either of these are quite similar. Let's look at the
-X.509 stuff first:
-\begin{verbatim}
-namespace X509 {
-   MemoryVector<byte> BER_encode(const Public_Key& key);
-   std::string PEM_encode(const Public_Key& out);
-
-   Public_Key* load_key(DataSource& in);
-   Public_Key* load_key(const SecureVector<byte>& buffer);
-}
-\end{verbatim}
-
-The function \function{X509::BER\_encode} will take any
-\type{Public\_Key} and return a standard binary structure representing
-the key which can be read by many other crypto libraries.
-
-The function \function{X509::PEM\_encode} does the same, but
-additionally formats it into a text format with headers and base64
-encoding. Using PEM is \emph{highly} recommended for many reasons,
-including compatibility with other software, for transmission over
-8-bit unclean channels, because it can be identified by a human
-without special tools, and because it sometimes allows more sane
-behavior of tools that process the data.
-
-For loading a public key, use one of the variants of
-\function{load\_key}. This function will return a newly allocated key
-based on the data from whatever source it is using (assuming, of
-course, the source is in fact storing a representation of a public
-key). The encoding used (PEM or BER) need not be specified; the format
-will be detected automatically. The key is allocated with
-\function{new}, and should be released with \function{delete} when you
-are done with it. The first takes a generic \type{DataSource} that you
-have to create~--~the others are simple wrapper functions that take
-either a filename or a memory buffer.
-
-Here's an example of loading a public key and then encrypting with it:
-
-\begin{verbatim}
-   /* Might be RSA, might be ElGamal, might be ... */
-   Public_Key* key = X509::load_key("pubkey.asc");
-
-   /* This might throw an exception if the key doesn't support any
-      encryption operations
-   */
-
-   PK_Encryptor_EME encryptor(*key, "EME1(SHA-1)");
-
-   SecureVector<byte> ciphertext = encryptor.encrypt(msg, size_of_msg);
-\end{verbatim}
-
-\subsubsection{Private Keys}
-
-There are two different options for private key import/export. The first is a
-plaintext version of the private key. This is supported by the following
-functions:
-
-\begin{verbatim}
-namespace PKCS8 {
-   SecureVector<byte> BER_encode(const Private_Key& key);
-   std::string PEM_encode(const Private_Key& key);
-}
-\end{verbatim}
-
-These functions are similiar to the X.509 functions described
-previously. The only difference is that they take a
-\type{Private\_Key} object instead. In most situations, using these is
-a bad idea, because anyone can come along and grab the private key
-without having to know any passwords or other secrets. Unless you have
-very particular security requirements, always use the versions that
-encrypt the key based on a passphrase. For importing, the same
-functions can be used for encrypted and unencrypted keys.
-
-The other way to export a PKCS \#8 key is to first encode it in the
-same manner as done above, then encrypt it using a passphrase, and
-store the whole thing into another structure. This method is
-definitely preferred, since otherwise the private key is
-unprotected. The algorithms and structures used here are standardized
-by PKCS \#5 and PKCS \#8, and can be read by many other crypto
-libraries.
-
-\begin{verbatim}
-namespace PKCS8 {
-   SecureVector<byte> BER_encode(const Private_Key& key,
-                                 RandomNumberGenerator& rng,
-                                 const std::string& pass,
-                                 const std::string& pbe_algo = "");
-
-   std::string PEM_encode(const Private_Key& key,
-                          RandomNumberGenerator& rng,
-                          const std::string& pass,
-                          const std::string& pbe_algo = "");
-}
-\end{verbatim}
-
-There are three new arguments needed here to support the encryption
-process in addition to the private key itself. The first is a
-\type{RandomNumberGenerator}, which is needed for various purposes
-internally. The \arg{pass} argument is the passphrase that will be
-used to encrypt the key. Both of these are required. The final
-(optional) argument is \arg{pbe}; this specifies a particular password
-based encryption (or PBE) algorithm. If you don't specify a PBE,
-a compiled in default will be used; this should be fine.
-
-Last but not least, there are some functions that will load (and
-decrypt, if necessary) a PKCS \#8 private key:
-
-\begin{verbatim}
-namespace PKCS8 {
-   Private_Key* load_key(DataSource& in,
-                         RandomNumberGenerator& rng,
-                         const User_Interface& ui);
-
-   Private_Key* load_key(DataSource& in,
-                         RandomNumberGenerator& rng,
-                         std::string passphrase = "");
-
-   Private_Key* load_key(const std::string& filename,
-                         RandomNumberGenerator& rng,
-                         const User_Interface& ui);
-
-   Private_Key* load_key(const std::string& filename,
-                         RandomNumberGenerator& rng,
-                         const std::string& passphrase = "");
-}
-\end{verbatim}
-
-The versions that take \type{std::string} \arg{passphrase}s are
-primarily for compatibility, but they are useful in limited
-circumstances. The \type{User\_Interface} versions are how
-\function{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 \type{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 \type{User\_Interface} is rather
-dumb, and acts rather like the versions taking the \type{std::string};
-it tries the passphrase passed in first, and then it cancels.
-
-All versions need access to a \type{RandomNumberGenerator} in order to
-perform probabilistic tests on the loaded key material.
-
-After loading a key, you can use \function{dynamic\_cast} to find out
-what operations it supports, and use it appropriately. Remember to
-\function{delete} the object once you are done with it.
-
-\subsubsection{Limitations}
-
-As of now Nyberg-Rueppel and Rabin-Williams keys cannot be imported or
-exported, because they have no official ASN.1 OID or definition. ElGamal keys
-can (as of Botan 1.3.8) be imported and exported, but the only other
-implementation that supports the format is Peter Gutmann's Cryptlib. If you
-can help it, stick to RSA and DSA.
-
-\emph{Note}: Currently NR and RW are given basic ASN.1 key formats (which
-mirror DSA and RSA, respectively), which means that, if they are assigned an
-OID, they can be imported and exported just as easily as RSA and DSA. You can
-assign them an OID by putting a line in a Botan configuration file, calling
-\function{OIDS::add\_oid}, or editing \filename{src/policy.cpp}. Be warned that
-it is possible that a future version will use a format that is different from
-the current one (\ie, a newly standardized format).
-
-\section{Certificate Handling}
-
-A certificate is a binding between some identifying information
-(called a \emph{subject}) and a public key. This binding is asserted
-by a signature on the certificate, which is placed there by some
-authority (the \emph{issuer}) that at least claims that it knows the
-subject named in the certificate really ``owns'' the private key
-corresponding to the public key in the certificate.
-
-The major certificate format in use today is X.509v3, designed by ISO and
-further hacked on by dozens (hundreds?) of other organizations.
-
-When working with certificates, the main class to remember is
-\type{X509\_Certificate}. You can read an object of this type, but you
-can't create one on the fly; a CA object is necessary for making a new
-certificate. So for the most part, you only have to worry about
-reading them in, verifying the signatures, and getting the bits of
-data in them (most commonly the public key, and the information about
-the user of that key). An X.509v3 certificate can contain a literally
-infinite number of items related to all kinds of things. Botan doesn't
-support a lot of them, because nobody uses them and they're an
-impossible mess to work with. This section only documents the most
-commonly used ones of the ones that are supported; for the rest, read
-\filename{x509cert.h} and \filename{asn1\_obj.h} (which has the
-definitions of various common ASN.1 constructs used in X.509).
-
-\subsection{So what's in an X.509 certificate?}
-
-Obviously, you want to be able to get the public key. This is achieved
-by calling the member function \function{subject\_public\_key}, which
-will return a \type{Public\_Key*}. As to what to do with this, read
-about \function{load\_key} in the section ``Importing and Exporting PK
-Keys''. In the general case, this could be any kind of public key,
-though 99\% of the time it will be an RSA key. However, Diffie-Hellman
-and DSA keys are also supported, so be careful about how you treat
-this. It is also a wise idea to examine the value returned by
-\function{constraints}, to see what uses the public key is approved
-for.
-
-The second major piece of information you'll want is the
-name/email/etc of the person to whom this certificate is
-assigned. Here is where things get a little nasty. X.509v3 has two
-(well, mostly just two $\ldots$) different places where you can stick
-information about the user: the \emph{subject} field, and in an
-extension called \emph{subjectAlternativeName}. The \emph{subject}
-field is supposed to only included the following information: country,
-organization, an organizational sub-unit name, and a so-called common
-name. The common name is usually the name of the person, or it could
-be a title associated with a position of some sort in the
-organization. It may also include fields for state/province and
-locality. What a locality is, nobody knows, but it's usually given as
-a city name.
-
-Botan doesn't currently support any of the Unicode variants used in
-ASN.1 (UTF-8, UCS-2, and UCS-4), any of which could be used for the
-fields in the DN. This could be problematic, particularly in Asia and
-other areas where non-ASCII characters are needed for most names. The
-UTF-8 and UCS-2 string types \emph{are} accepted (in fact, UTF-8 is
-used when encoding much of the time), but if any of the characters
-included in the string are not in ISO 8859-1 (\ie 0 \ldots 255), an
-exception will get thrown. Currently the \type{ASN1\_String} type
-holds its data as ISO 8859-1 internally (regardless of local character
-set); this would have to be changed to hold UCS-2 or UCS-4 in order to
-support Unicode (also, many interfaces in the X.509 code would have to
-accept or return a \type{std::wstring} instead of a
-\type{std::string}).
-
-Like the distinguished names, subject alternative names can contain a
-lot of things that Botan will flat out ignore (most of which you would
-likely never want to use). However, there are three very useful pieces
-of information that this extension might hold: an email address
-(``[email protected]''), a DNS name (``somehost.site2.com''), or a URI
-(``http://www.site3.com'').
-
-So, how to get the information? Call \function{subject\_info} with the
-name of the piece of information you want, and it will return a
-\type{std::string} that is either empty (signifying that the
-certificate doesn't have this information), or has the information
-requested. There are several names for each possible item, but the
-most easily readable ones are: ``Name'', ``Country'',
-``Organization'', ``Organizational Unit'', ``Locality'', ``State'',
-``RFC822'', ``URI'', and ``DNS''. These values are returned as a
-\type{std::string}.
-
-You can also get information about the issuer of the certificate in the same
-way, using \function{issuer\_info}.
-
-\subsubsection{X.509v3 Extensions}
-
-X.509v3 specifies a large number of possible extensions. Botan
-supports some, but by no means all of them. This section lists which
-ones are supported, and notes areas where there may be problems with
-the handling.
-
-\begin{list}{$\cdot$}
-  \item Key Usage and Extended Key Usage: No problems known.
-  \item
-
-  \item Basic Constraints: No problems known. The default for a v1/v2
-        certificate is assume it's a CA if and only if the option
-        ``x509/default\_to\_ca'' is set. A v3 certificate is marked as a CA if
-        (and only if) the basic constraints extension is present and set for a
-        CA cert.
-
-  \item Subject Alternative Names: Only the ``rfc822Name'', ``dNSName'', and
-        ``uniformResourceIdentifier'' fields will be stored; all others are
-        ignored.
-
-  \item Issuer Alternative Names: Same restrictions as the Subject Alternative
-        Names extension. New certificates generated by Botan never include the
-        issuer alternative name.
-
-  \item Authority Key Identifier: Only the version using KeyIdentifier is
-        supported. If the GeneralNames version is used and the extension is
-        critical, an exception is thrown. If both the KeyIdentifier and
-        GeneralNames versions are present, then the KeyIdentifier will be
-        used, and the GeneralNames ignored.
-
-  \item Subject Key Identifier: No problems known.
-\end{list}
-
-\subsubsection{Revocation Lists}
-
-It will occasionally happen that a certificate must be revoked before
-its expiration date. Examples of this happening include the private
-key being compromised, or the user to which it has been assigned
-leaving an organization. Certificate revocation lists are an answer to
-this problem (though online certificate validation techniques are
-starting to become somewhat more popular). Every once in a while the
-CA will release a new CRL, listing all certificates that have been
-revoked. Also included is various pieces of information like what time
-a particular certificate was revoked, and for what reason. In most
-systems, it is wise to support some form of certificate revocation,
-and CRLs handle this easily.
-
-For most users, processing a CRL is quite easy. All you have to do is call the
-constructor, which will take a filename (or a \type{DataSource\&}). The CRLs
-can either be in raw BER/DER, or in PEM format; the constructor will figure out
-which format without any extra information. For example:
-
-\begin{verbatim}
-   X509_CRL crl1("crl1.der");
-
-   DataSource_Stream in("crl2.pem");
-   X509_CRL crl2(in);
-\end{verbatim}
-
-After that, pass the \type{X509\_CRL} object to a \type{X509\_Store} object
-with \type{X509\_Code} \function{add\_crl}(\type{X509\_CRL}), and all future
-verifications will take into account the certificates listed, assuming
-\function{add\_crl} returns \type{VERIFIED}. If it doesn't return
-\type{VERIFIED}, then the return value is an error code signifying that the CRL
-could not be processed due to some problem (which could range from the issuing
-certificate not being found, to the CRL having some format problem). For more
-about the \type{X509\_Store} API, read the section later in this chapter.
-
-\subsection{Reading Certificates}
-
-\type{X509\_Certificate} has two constructors, each of which takes a source of
-data; a filename to read, and a \type{DataSource\&}.
-
-\subsection{Storing and Using Certificates}
-
-If you read a certificate, you probably want to verify the signature on
-it. However, consider that to do so, we may have to verify the signature on the
-certificate that we used to verify the first certificate, and on and on until
-we hit the top of the certificate tree somewhere. It would be a might huge pain
-to have to handle all of that manually in every application, so there is
-something that does it for you: \type{X509\_Store}.
-
-The basic operations are: put certificates and CRLs into it, search
-for certificates, and attempt to verify certificates. That's about
-it. In the future, there will be support for online retrieval of
-certificates and CRLs (\eg with the HTTP cert-store interface
-currently under consideration by PKIX).
-
-\subsubsection{Adding Certificates}
-
-You can add new certificates to a certificate store using any of these
-functions:
-
-\function{add\_cert}(\type{const X509\_Certificate\&} \arg{cert},
-                     \type{bool} \arg{trusted} \type{= false})
-
-\function{add\_certs}(\type{DataSource\&} \arg{source})
-
-\function{add\_trusted\_certs}(\type{DataSource\&} \arg{source})
-
-The versions that take a \type{DataSource\&} will add all the certificates
-that it can find in that source.
-
-All of them add the cert(s) to the store. The 'trusted' certificates are the
-ones that you have some reason to trust are genuine. For example, say your
-application is working with certificates that are owned by employees of some
-company, and all of their certificates are signed by the company CA, whose
-certificate is in turned signed by a commercial root CA. What you would then do
-is include the certificate of the commercial CA with your application, and read
-it in as a trusted certificate. From there, you could verify the company CA's
-certificate, and then use that to verify the end user's certificates. Only
-self-signed certificates may be considered trusted.
-
-\subsubsection{Adding CRLs}
-
-\type{X509\_Code} \function{add\_crl}(\type{const X509\_CRL\&} \arg{crl});
-
-This will process the CRL and mark the revoked certificates. This will also
-work if a revoked certificate is added to the store sometime after the CRL is
-processed. The function can return an error code (listed later), or will return
-\type{VERIFIED} if everything completed successfully.
-
-\subsubsection{Storing Certificates}
-
-You can output a set of certificates by calling \function{PEM\_encode}, which
-will return a \type{std::string} containing each of the certificates in the
-store, PEM encoded and concatenated. This simple format can easily be read by
-both Botan and other libraries/applications.
-
-\subsubsection{Searching for Certificates}
-
-You can find certificates in the store with a series of functions contained
-in the \function{X509\_Store\_Search} namespace:
-
-\begin{verbatim}
-namespace X509_Store_Search {
-std::vector<X509_Certificate> by_email(const X509_Store& store,
-                                       const std::string& email_addr);
-std::vector<X509_Certificate> by_name(const X509_Store& store,
-                                      const std::string& name);
-std::vector<X509_Certificate> by_dns(const X509_Store&,
-                                     const std::string& dns_name);
-}
-\end{verbatim}
-
-These functions will return a (possibly empty) vector of certificates from
-\arg{store} matching your search criteria. The email address and DNS name
-searches are case-insensitive but are sensitive to extra whitespace and so
-on. The name search will do case-insensitive substring matching, so, for
-example, calling \function{X509\_Store\_Search::by\_name}(\arg{your\_store},
-``dob'') will return certificates for ``J.R. 'Bob' Dobbs'' and
-``H. Dobbertin'', assuming both of those certificates are in \arg{your\_store}.
-
-You could then display the results to a user, and allow them to select the
-appropriate one. Searching using an email address as the key is usually more
-effective than the name, since email addresses are rarely shared.
-
-\subsubsection{Certificate Stores}
-
-An object of type \type{Certificate\_Store} is a generalized interface
-to an external source for certificates (and CRLs). Examples of such a
-store would be one that looked up the certificates in a SQL database,
-or by contacting a CGI script running on a HTTP server. There are
-currently three mechanisms for looking up a certificate, and one for
-retrieving CRLs. By default, most of these mechanisms will return an
-empty \type{std::vector} of \type{X509\_Certificate}. This storage
-mechanism is \emph{only} queried when doing certificate validation: it
-allows you to distribute only the root key with an application, and
-let some online method handle getting all the other certificates that
-are needed to validate an end entity certificate. In particular, the
-search routines will not attempt to access the external database.
-
-The three certificate lookup methods are \function{by\_SKID} (Subject Key
-Identifier), \function{by\_name} (the CommonName DN entry), and
-\function{by\_email} (stored in either the distinguished name, or in a
-subjectAlternativeName extension). The name and email versions take a
-\type{std::string}, while the SKID version takes a \type{SecureVector<byte>}
-containing the subject key identifier in raw binary. You can choose not to
-implement \function{by\_name} or \function{by\_email}, but \function{by\_SKID}
-is mandatory to implement, and, currently, is the only version that is used by
-\type{X509\_Store}.
-
-Finally, there is a method for finding CRLs, called
-\function{get\_crls\_for}, that takes an \type{X509\_Certificate}
-object, and returns a \type{std::vector} of \type{X509\_CRL}. While
-normally there will be only one CRL, the use of the vector makes it
-easy to return no CRLs (\eg, if the certificate store doesn't support
-retrieving them), or return multiple ones (for example, if the
-certificate store can't determine precisely which key was used to sign
-the certificate). Implementing the function is optional, and by
-default will return no CRLs. If it is available, it will be used by
-\type{X509\_CRL}.
-
-As for using such a store, you have to tell \type{X509\_Store} about
-it, by calling the \type{X509\_Store} member function
-
-\function{add\_new\_certstore}(\type{Certificate\_Store}* \arg{new\_store})
-
-The argument, \arg{new\_store}, will be deleted by \type{X509\_Store}'s
-destructor, so make sure to allocate it with \function{new}.
-
-\subsubsection{Verifying Certificates}
-
-There is a single function in \type{X509\_Store} related to verifying a
-certificate:
-
-\type{X509\_Code}
-\function{validate\_cert}(\type{const X509\_Certificate\&} \arg{cert},
-                          \type{Cert\_Usage} \arg{usage} = \type{ANY})
-
-This function will return \type{VERIFIED} if the certificate can
-safely be considered valid for the usage(s) described by \arg{usage},
-and an error code if it is not. Naturally, things are a bit more
-complicated than that. The enum \type{Cert\_Usage} is defined inside
-the \type{X509\_Store} class, it (currently) can take on any of the
-values \type{ANY} (any usage is OK), \type{TLS\_SERVER} (for SSL/TLS
-server authentication), \type{TLS\_CLIENT} (for SSL/TLS client
-authentication), \type{CODE\_SIGNING}, \type{EMAIL\_PROTECTION} (email
-encryption, usually this means S/MIME), \type{TIME\_STAMPING} (in
-theory any time stamp application, usually IETF PKIX's Time Stamp
-Protocol), or \type{CRL\_SIGNING}. Note that Microsoft's code signing
-system, certainly the most widely used, uses a completely different
-(and mostly undocumented) method for marking certificates for code
-signing.
-
-First, how does it know if a certificate is valid? A certificate is
-valid if both of the following hold: a) the signature in the
-certificate can be verified using the public key in the issuer's
-certificate, and b) the issuer's certificate is a valid CA
-certificate. Note that this definition is recursive. We get out of
-this by ``bottoming out'' when we reach a certificate that we consider
-trusted. In general this will either be a commercial root CA, or an
-organization or application specific CA.
-
-There are a few other restrictions (validity periods, key usage
-restrictions, etc), but the above summarizes the major points of the
-validation algorithm. In theory, Botan implements the certificate path
-validation algorithm given in RFC 2459, but in practice it does not
-(yet), because we don't support the X.509v3 policy or name constraint
-extensions.
-
-Possible values for \arg{usage} are \type{TLS\_SERVER},
-\type{TLS\_CLIENT}, \type{CODE\_SIGNING}, \type{EMAIL\_PROTECTION},
-\type{CRL\_SIGNING}, and \type{TIME\_STAMPING}, and \type{ANY}. The
-default \type{ANY} does not mean valid for any use, it means ``is
-valid for some usage''. This is usually what you want; requiring that
-a random certificate support a particular usage will likely result in
-a lot of failures, unless your application is very careful to always
-issue certificates with the proper extensions, and you never use
-certificates generated by other apps.
-
-Return values for \function{validate\_cert} (and \function{add\_crl}) include:
-
-\begin{list}{$\cdot$}
-  \item VERIFIED: The certificate is valid for the specified use.
-  \item
-  \item INVALID\_USAGE: The certificate cannot be used for the specified use.
-
-   \item CANNOT\_ESTABLISH\_TRUST: The root certificate was not marked as
-         trusted.
-   \item CERT\_CHAIN\_TOO\_LONG: The certificate chain exceeded the length
-         allowed by a basicConstraints extension.
-   \item SIGNATURE\_ERROR: An invalid signature was found
-   \item POLICY\_ERROR: Some problem with the certificate policies was found.
-
-   \item CERT\_FORMAT\_ERROR: Some format problem was found in a certificate.
-   \item CERT\_ISSUER\_NOT\_FOUND: The issuer of a certificate could not be
-         found.
-   \item CERT\_NOT\_YET\_VALID: The certificate is not yet valid.
-   \item CERT\_HAS\_EXPIRED: The certificate has expired.
-   \item CERT\_IS\_REVOKED: The certificate has been revoked.
-
-   \item CRL\_FORMAT\_ERROR: Some format problem was found in a CRL.
-   \item CRL\_ISSUER\_NOT\_FOUND: The issuer of a CRL could not be found.
-   \item CRL\_NOT\_YET\_VALID: The CRL is not yet valid.
-   \item CRL\_HAS\_EXPIRED: The CRL has expired.
-
-   \item CA\_CERT\_CANNOT\_SIGN: The CA certificate found does not have an
-         contain a public key that allows signature verification.
-   \item CA\_CERT\_NOT\_FOR\_CERT\_ISSUER: The CA cert found is not allowed to
-         issue certificates.
-   \item CA\_CERT\_NOT\_FOR\_CRL\_ISSUER: The CA cert found is not allowed to
-         issue CRLs.
-
-  \item UNKNOWN\_X509\_ERROR: Some other error occurred.
-
-\end{list}
-
-\subsection{Certificate Authorities}
-
-Setting up a CA for X.509 certificates is perhaps the easiest thing to
-do related to X.509. A CA is represented by the type \type{X509\_CA},
-which can be found in \filename{x509\_ca.h}. A CA always needs its own
-certificate, which can either be a self-signed certificate (see below
-on how to create one) or one issued by another CA (see the section on
-PKCS \#10 requests). Creating a CA object is done by the following
-constructor:
-
-\begin{verbatim}
-   X509_CA(const X509_Certificate& cert, const Private_Key& key);
-\end{verbatim}
-
-The private key is the private key corresponding to the public key in the
-CA's certificate.
-
-Requests for new certificates are supplied to a CA in the form on PKCS
-\#10 certificate requests (called a \type{PKCS10\_Request} object in
-Botan). These are decoded in a similar manner to
-certificates/CRLs/etc. A request is vetted by humans (who somehow
-verify that the name in the request corresponds to the name of the
-entity who requested it), and then signed by a CA key, generating a
-new certificate.
-
-\begin{verbatim}
-   X509_Certificate sign_request(const PKCS10_Request&) const;
-\end{verbatim}
-
-\subsubsection{Generating CRLs}
-
-As mentioned previously, the ability to process CRLs is highly important in
-many PKI systems. In fact, according to strict X.509 rules, you must not
-validate any certificate if the appropriate CRLs are not available (though
-hardly any systems are that strict). In any case, a CA should have a valid CRL
-available at all times.
-
-Of course, you might be wondering what to do if no certificates have
-been revoked. Never fear; empty CRLs, which revoke nothing at all, can
-be issued. To generate a new, empty CRL, just call \type{X509\_CRL}
-\function{X509\_CA::new\_crl}(\type{u32bit}~\arg{seconds}~=~0)~--~it
-will create a new, empty, CRL. If \arg{seconds} is the default 0, then
-the normal default CRL next update time (the value of the
-``x509/crl/next\_update'') will be used. If not, then \arg{seconds}
-specifies how long (in seconds) it will be until the CRL's next update
-time (after this time, most clients will reject the CRL as too old).
-
-On the other hand, you may have issued a CRL before. In that case, you will
-want to issue a new CRL that contains all previously revoked
-certificates, along with any new ones. This is done by calling the
-\type{X509\_CA} member function
-\function{update\_crl}(\type{X509\_CRL}~\arg{old\_crl},
-\type{std::vector<CRL\_Entry>}~\arg{new\_revoked},
-\type{u32bit}~\arg{seconds}~=~0), where \type{X509\_CRL} is the last CRL this
-CA issued, and \arg{new\_revoked} is a list of any newly revoked certificates.
-The function returns a new \type{X509\_CRL} to make available for clients. The
-semantics for the \arg{seconds} argument is the same as \function{new\_crl}.
-
-The \type{CRL\_Entry} type is a structure that contains, at a minimum, the
-serial number of the revoked certificate. As serial numbers are never repeated,
-the pairing of an issuer and a serial number (should) distinctly identify any
-certificate. In this case, we represent the serial number as a
-\type{SecureVector<byte>} called \arg{serial}. There are two additional
-(optional) values, an enumeration called \type{CRL\_Code} that specifies the
-reason for revocation (\arg{reason}), and an object that represents the time
-that the certificate became invalid (if this information is known).
-
-If you wish to remove an old entry from the CRL, insert a new entry for the
-same cert, with a \arg{reason} code of \type{DELETE\_CRL\_ENTRY}. For example,
-if a revoked certificate has expired 'normally', there is no reason to continue
-to explicitly revoke it, since clients will reject the cert as expired in any
-case.
-
-\subsubsection{Self-Signed Certificates}
-
-Generating a new self-signed certificate can often be useful, for
-example when setting up a new root CA, or for use in email
-applications. The library provides a utility function for this:
-
-\begin{verbatim}
-namespace X509 {
-   X509_Certificate create_self_signed_cert(const X509_Cert_Options& opts,
-                                            const Private_Key& key);
-}
-\end{verbatim}
-
-Where \arg{key} is obviously the private key you wish to use (the public key,
-used in the certificate itself, is extracted from the private key), and
-\arg{opts} is an structure that has various bits of information that will be
-used in creating the certificate (this structure, and its use, is discussed
-below). This function is found in the header \filename{x509self.h}. There is an
-example of using this function in the \filename{self\_sig} example.
-
-\subsubsection{Creating PKCS \#10 Requests}
-
-Also in \filename{x509self.h}, there is a function for generating new PKCS \#10
-certificate requests.
-
-\begin{verbatim}
-namespace X509 {
-   PKCS10_Request create_cert_req(const X509_Cert_Options&,
-                                  const Private_Key&);
-}
-\end{verbatim}
-
-This function acts quite similarly to \function{create\_self\_signed\_cert},
-except it instead returns a PKCS \#10 certificate request. After creating it,
-one would typically transmit it to a CA, who signs it and returns a freshly
-minted X.509 certificate. There is an example of using this function in the
-\filename{pkcs10} example.
-
-\subsubsection{Certificate Options}
-
-What is this \type{X509\_Cert\_Options} thing we've been passing
-around? It's a class representing a bunch of information that will end
-up being stored into the certificate. This information comes in 3
-major flavors: information about the subject (CA or end-user), the
-validity period of the certificate, and restrictions on the usage of
-the certificate.
-
-First and foremost is a number of \type{std::string} members, which contains
-various bits of information about the user: \arg{common\_name},
-\arg{serial\_number}, \arg{country}, \arg{organization}, \arg{org\_unit},
-\arg{locality}, \arg{state}, \arg{email}, \arg{dns\_name}, and \arg{uri}. As
-many of these as possible should be filled it (especially an email address),
-though the only required ones are \arg{common\_name} and \arg{country}.
-
-There is another value that is only useful when creating a PKCS \#10 request,
-which is called \arg{challenge}. This is a challenge password, which you can
-later use to request certificate revocation (\emph{if} the CA supports doing
-revocations in this manner).
-
-Then there is the validity period; these are set with \function{not\_before}
-and \function{not\_after}. Both of these functions also take a
-\type{std::string}, which specifies when the certificate should start being
-valid, and when it should stop being valid. If you don't set the starting
-validity period, it will automatically choose the current time. If you don't
-set the ending time, it will choose the starting time plus a default time
-period. The arguments to these functions specify the time in the following
-format: ``2002/11/27 1:50:14''. The time is in 24-hour format, and the date is
-encoded as year/month/day. The date must be specified, but you can omit the
-time or trailing parts of it, for example ``2002/11/27 1:50'' or
-``2002/11/27''.
-
-Lastly, you can set constraints on a key. The one you're mostly likely to want
-to use is to create (or request) a CA certificate, which can be done by calling
-the member function \function{CA\_key}. This should only be used when needed.
-
-Other constraints can be set by calling the member functions
-\function{add\_constraints} and \function{add\_ex\_constraints}. The
-first takes a \type{Key\_Constraints} value, and replaces any
-previously set value. If no value is set, then the certificate key is
-marked as being valid for any usage.  You can set it to any of the
-following (for more than one usage, OR them together):
-\type{DIGITAL\_SIGNATURE}, \type{NON\_REPUDIATION},
-\type{KEY\_ENCIPHERMENT}, \type{DATA\_ENCIPHERMENT},
-\type{KEY\_AGREEMENT}, \type{KEY\_CERT\_SIGN}, \type{CRL\_SIGN},
-\type{ENCIPHER\_ONLY}, \type{DECIPHER\_ONLY}. Many of these have quite
-special semantics, so you should either consult the appropriate
-standards document (such as RFC 3280), or just not call
-\function{add\_constraints}, in which case the appropriate values will
-be chosen for you.
-
-The second function, \function{add\_ex\_constraints}, allows you to specify an
-OID that has some meaning with regards to restricting the key to particular
-usages. You can, if you wish, specify any OID you like, but there is a set of
-standard ones that other applications will be able to understand. These are
-the ones specified by the PKIX standard, and are named ``PKIX.ServerAuth'' (for
-TLS server authentication), ``PKIX.ClientAuth'' (for TLS client
-authentication), ``PKIX.CodeSigning'', ``PKIX.EmailProtection'' (most likely
-for use with S/MIME), ``PKIX.IPsecUser'', ``PKIX.IPsecTunnel'',
-``PKIX.IPsecEndSystem'', and ``PKIX.TimeStamping''. You can call
-\function{add\_ex\_constraints} any number of times~--~each new OID will be
-added to the list to include in the certificate.
-
-\section{The Low-Level Interface}
-
-Botan has two different interfaces. The one documented in this section is meant
-more for implementing higher-level types (see the section on filters, earlier in
-this manual) than for use by applications. Using it safely requires a solid
-knowledge of encryption techniques and best practices, so unless you know, for
-example, what CBC mode and nonces are, and why PKCS \#1 padding is important,
-you should avoid this interface in favor of something working at a higher level
-(such as the CMS interface).
-
-\subsection{Basic Algorithm Abilities}
-
-There are a small handful of functions implemented by most of Botan's
-algorithm objects. Among these are:
-
-\noindent
-\type{std::string} \function{name}():
-
-Returns a human-readable string of the name of this algorithm. Examples of
-names returned are ``Blowfish'' and ``HMAC(MD5)''. You can turn names back into
-algorithm objects using the functions in \filename{lookup.h}.
-
-\noindent
-\type{void} \function{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.
-
-\noindent
-\function{clone}():
-
-This function is central to Botan's name-based interface. The \function{clone}
-has many different return types, such as \type{BlockCipher*} and
-\type{HashFunction*}, depending on what kind of object it is called on. Note
-that unlike Java's clone, this returns a new object in a ``pristine'' state;
-that is, operations done on the initial object before calling \function{clone}
-do not affect the initial state of the new clone.
-
-Cloned objects can (and should) be deallocated with the C++ \texttt{delete}
-operator.
-
-\subsection{Keys and IVs}
-
-Both symmetric keys and initialization values can be considered byte
-(or octet) strings. These are represented by the classes
-\type{SymmetricKey} and \type{InitializationVector}, which are
-subclasses of \type{OctetString}.
-
-Since often it's hard to distinguish between a key and IV, many things (such as
-key derivation mechanisms) return \type{OctetString} instead of
-\type{SymmetricKey} to allow its use as a key or an IV.
-
-\noindent
-\function{OctetString}(\type{u32bit} \arg{length}):
-
-This constructor creates a new random key of size \arg{length}.
-
-\noindent
-\function{OctetString}(\type{std::string} \arg{str}):
-
-The argument \arg{str} is assumed to be a hex string; it is converted to binary
-and stored. Whitespace is ignored.
-
-\noindent
-\function{OctetString}(\type{const byte} \arg{input}[], \type{u32bit}
-\arg{length}):
-
-This constructor copies its input.
-
-\subsection{Symmetrically Keyed Algorithms}
-
-Block ciphers, stream ciphers, and MACs are all keyed operations; to
-be useful, they have to be set to use a particular key, which is a
-randomly chosen string of bits of a specified length.  The length
-required by any particular algorithm may vary, depending on both the
-algorithm specification and the implementation. You can query any
-botan object to find out what key length(s) it supports.
-
-To make this similarity in terms of keying explicit, all algorithms of
-those types are derived from the \type{SymmetricAlgorithm} base
-class. This type has three functions:
-
-\noindent
-\type{void} \function{set\_key}(\type{const byte} \arg{key}[], \type{u32bit}
-\arg{length}):
-
-Most algorithms only accept keys of certain lengths. If you attempt to call
-\function{set\_key} with a key length that is not supported, the exception
-\type{Invalid\_Key\_Length} will be thrown. There is also another version of
-\function{set\_key} that takes a \type{SymmetricKey} as an argument.
-
-\noindent
-\type{bool} \function{valid\_keylength}(\type{u32bit} \arg{length}) const:
-
-This function returns true if a key of the given length will be accepted by
-the cipher.
-
-There are also three constant data members of every
-\type{SymmetricAlgorithm} object, which specify what limits there are
-on keys which that object can accept:
-
-MAXIMUM\_KEYLENGTH: The maximum length of a key. Usually, this is at
-most 32 (256 bits), even if the algorithm supports more. In a few rare
-cases larger keys will be supported.
-
-MINIMUM\_KEYLENGTH: The minimum length of a key. This is at least 1.
-
-KEYLENGTH\_MULTIPLE: The length of the key must be a multiple of this value.
-
-In all cases, \function{set\_key} must be called on an object before any data
-processing (encryption, decryption, etc) is done by that object. If this is not
-done, the results are undefined -- that is to say, Botan reserves the right in
-this situation to do anything from printing a nasty, insulting message on the
-screen to dumping core.
-
-\subsection{Block Ciphers}
-
-Block ciphers implement the interface \type{BlockCipher}, found in
-\filename{base.h}, as well as the \type{SymmetricAlgorithm} interface.
-
-\noindent
-\type{void} \function{encrypt}(\type{const byte} \arg{in}[],
-                               \type{byte} \arg{out}[]) const
-
-\noindent
-\type{void} \function{encrypt}(\type{byte} \arg{block}[]) const
-
-These functions apply the block cipher transformation to \arg{in} and
-place the result in \arg{out}, or encrypts \arg{block} in place
-(\arg{in} may be the same as \arg{out}). Exactly one block will be
-encrypted; you can find out the block size of the cipher you are
-working with by calling the member function \function{block\_size}.
-\type{BlockCipher}s have similar functions \function{decrypt}, which
-perform the inverse operation.
-
-If you want to process multiple blocks in parallel, use
-\function{encrypt\_n} and \function{decrypt\_n}.
-
-\begin{verbatim}
-AES_128 cipher;
-SymmetricKey key(cipher.MAXIMUM_KEYLENGTH); // randomly created
-cipher.set_key(key);
-
-byte in[16] = { /* secrets */ };
-byte out[16];
-cipher.encrypt(in, out);
-\end{verbatim}
-
-\subsection{Stream Ciphers}
-
-Stream ciphers are somewhat different from block ciphers, in that 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).
-
-\noindent
-\type{void} \function{encrypt}(\type{const byte} \arg{in}[], \type{byte}
-\arg{out}[], \type{u32bit} \arg{length})
-
-\noindent
-\type{void} \function{encrypt}(\type{byte} \arg{data}[], \type{u32bit}
-\arg{length}):
-
-These functions encrypt the arbitrary length (well, less than 4 gigabyte long)
-string \arg{in} and place it into \arg{out}, or encrypts it in place in
-\arg{data}. The \function{decrypt} functions look just like
-\function{encrypt}.
-
-Stream ciphers implement the \type{SymmetricAlgorithm} interface.
-
-Some stream ciphers support random access to any point in their cipher
-stream. For such ciphers, calling \type{void} \function{seek}(\type{u32bit}
-\arg{byte}) will change the cipher's state so that it is as if the cipher had been
-keyed as normal, then encrypted \arg{byte} -- 1 bytes of data (so the next byte
-in the cipher stream is byte number \arg{byte}).
-
-\subsection{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
-\type{BufferedComputation}, which has the following functions.
-
-\noindent
-\type{size\_t} \function{output\_length}()
-
-Return the size of the output of this function.
-
-\type{void} \function{update}(\type{const byte} \arg{input}[], \type{u32bit}
-\arg{length})
-
-\noindent
-\type{void} \function{update}(\type{byte} \arg{input})
-
-\noindent
-\type{void} \function{update}(\type{const std::string \&} \arg{input})
-
-Updates the hash/mac calculation with \arg{input}.
-
-\noindent
-\type{void} \function{final}(\type{byte} \arg{out}[])
-
-\noindent
-\type{SecureVector<byte>} \function{final}():
-
-Complete the hash/MAC calculation and place the result into \arg{out}.
-For the argument taking an array, exactly \function{output\_length}()
-bytes will be written. After you call \function{final}, the hash
-function is reset to its initial state, so it may be reused
-immediately.
-
-The second method of using final is to call it with no arguments at
-all, as shown in the second prototype. It will return the hash/mac
-value in a memory buffer.
-
-There is also a pair of functions called \function{process}. They are
-a combination of a single \function{update}, and \function{final}.
-Both versions return the final value, rather than placing it an
-array. Calling \function{process} with a single byte value isn't
-available, mostly because it would rarely be useful.
-
-A MAC can be viewed (in most cases) as a keyed hash function, so
-classes that are derived from \type{MessageAuthenticationCode} have
-\function{update} and \function{final} classes just like a
-\type{HashFunction} (and like a \type{HashFunction}, after
-\function{final} is called, it can be used to make a new MAC right
-away; the key is kept around).
-
-A MAC has the \type{SymmetricAlgorithm} interface in addition to the
-\type{BufferedComputation} interface.
-
-\section{Random Number Generators}
-
-The random number generators provided in Botan are meant for creating
-keys, IVs, padding, nonces, and anything else that requires 'random'
-data. It is important to remember that the output of these classes
-will vary, even if they are supplied with ethe same seed (\ie, two
-\type{Randpool} objects with similar initial states will not produce
-the same output, because the value of high resolution timers is added
-to the state at various points).
-
-To ensure good quality output, a PRNG needs to be seeded with truly random data
-(such as that produced by a hardware RNG). Typically, you will use an
-\type{EntropySource} (see below). To add entropy to a PRNG, you can use
-\type{void} \function{add\_entropy}(\type{const byte} \arg{data}[],
-\type{u32bit} \arg{length}) or (better), use the \type{EntropySource}
-interface.
-
-Once a PRNG has been initialized, you can get a single byte of random data by
-calling \type{byte} \function{random()}, or get a large block by calling
-\type{void} \function{randomize}(\type{byte} \arg{data}[], \type{u32bit}
-\arg{length}), which will put random bytes into each member of the array from
-indexes 0 $\ldots$ \arg{length} -- 1.
-
-You can avoid all the problems inherent in seeding the PRNG by using the
-globally shared PRNG, described later in this section.
-
-\subsection{Randpool}
-
-\type{Randpool} is the primary PRNG within Botan. In recent versions all uses
-of it have been wrapped by an implementation of the X9.31 PRNG (see below). If
-for some reason you should have cause to create a PRNG instead of using the
-``global'' one owned by the library, it would be wise to consider the same on
-the grounds of general caution; while \type{Randpool} is designed with known
-attacks and PRNG weaknesses in mind, it is not an standard/official PRNG. The
-remainder of this section is a (fairly technical, though high-level) description
-of the algorithms used in this PRNG. Unless you have a specific interest in
-this subject, the rest of this section might prove somewhat uninteresting.
-
-\type{Randpool} has an internal state called pool, which is 512 bytes
-long. This is where entropy is mixed into and extracted from. There is also a
-small output buffer (called buffer), which holds the data which has already
-been generated but has just not been output yet.
-
-It is based around a MAC and a block cipher (which are currently HMAC(SHA-256)
-and AES-256). Where a specific size is mentioned, it should be taken as a
-multiple of the cipher's block size. For example, if a 256-bit block cipher
-were used instead of AES, all the sizes internally would double. Every time
-some new output is needed, we compute the MAC of a counter and a high
-resolution timer. The resulting MAC is XORed into the output buffer (wrapping
-as needed), and the output buffer is then encrypted with AES, producing 16
-bytes of output.
-
-After 8 blocks (or 128 bytes) have been produced, we mix the pool. To do this,
-we first rekey both the MAC and the cipher; the new MAC key is the MAC of the
-current pool under the old MAC key, while the new cipher key is the MAC of the
-current pool under the just-chosen MAC key. We then encrypt the entire pool in
-CBC mode, using the current (unused) output buffer as the IV. We then generate
-a new output buffer, using the mechanism described in the previous paragraph.
-
-To add randomness to the PRNG, we compute the MAC of the input and XOR the
-output into the start of the pool. Then we remix the pool and produce a new
-output buffer. The initial MAC operation should make it very hard for chosen
-inputs to harm the security of \type{Randpool}, and as HMAC should be able to
-hold roughly 256 bits of state, it is unlikely that we are wasting much input
-entropy (or, if we are, it doesn't matter, because we have a very abundant
-supply).
-
-\subsection{ANSI X9.31}
-
-\type{ANSI\_X931\_PRNG} is the standard issue X9.31 Appendix A.2.4 PRNG, though
-using AES-256 instead of 3DES as the block cipher. This PRNG implementation has
-been checked against official X9.31 test vectors.
-
-Internally, the PRNG holds a pointer to another PRNG (typically
-Randpool). This internal PRNG generates the key and seed used by the
-X9.31 algorithm, as well as the date/time vectors. Each time an X9.31
-PRNG object receives entropy, it passes it along to the PRNG it is
-holding, and then pulls out some random bits to generate a new key and
-seed. This PRNG considers itself seeded as soon as the internal PRNG
-is seeded.
-
-As of version 1.4.7, the X9.31 PRNG is by default used for all random number
-generation.
-
-\subsection{Entropy Sources}
-
-An \type{EntropySource} is an abstract representation of some method of gather
-``real'' entropy. This tends to be very system dependent. The \emph{only} way
-you should use an \type{EntropySource} is to pass it to a PRNG that will
-extract entropy from it -- never use the output directly for any kind of key or
-nonce generation!
-
-\type{EntropySource} has a pair of functions for getting entropy from
-some external source, called \function{fast\_poll} and
-\function{slow\_poll}. These pass a buffer of bytes to be written; the
-functions then return how many bytes of entropy were
-gathered. \type{EntropySource}s are usually used to seed the global
-PRNG using the functions found in the \namespace{Global\_RNG}
-namespace.
-
-Note for writers of \type{EntropySource}s: it isn't necessary to use any kind
-of cryptographic hash on your output. The data produced by an EntropySource is
-only used by an application after it has been hashed by the
-\type{RandomNumberGenerator} that asked for the entropy, thus any hashing
-you do will be wasteful of both CPU cycles and entropy.
-
-\section{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 \type{UI}, 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 (\type{UI} will probably be extended in the future
-to support other operations as they are needed). The base \type{UI}
-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 \emph{attached} to a terminal, and so on). But since you can
-subclass \type{UI} to use whatever method happens to be appropriate
-for your application, this isn't a big deal.
-
-\begin{verbatim}
-  std::string get_passphrase(const std::string& what,
-                             const std::string& source,
-                             UI_Result& result) const;
-\end{verbatim}
-
-The \arg{what} argument specifies what the passphrase is needed for (for
-example, PKCS \#8 key loading passes \arg{what} as ``PKCS \#8 private
-key''). This lets you provide the user with some indication of \emph{why} your
-application is asking for a passphrase; feel free to pass the string through
-\function{gettext(3)} or moral equivalent for i18n purposes. Similarly,
-\arg{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
-\arg{source} will be an empty string; be sure to account for this possibility
-when writing a \type{UI} subclass.
-
-The function returns the passphrase as the return value, and a status code in
-\arg{result} (either \type{OK} or \type{CANCEL\_ACTION}). If
-\type{CANCEL\_ACTION} is returned in \arg{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 \type{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 \type{UI} that uses GTK+ available on the web site. The
-\type{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 \type{UI} 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.
-
-\section{Botan's Modules}
-
-Botan comes with a variety of modules that can be compiled into the system.
-These will not be available on all installations of the library, but you can
-check for their availability based on whether or not certain macros are
-defined.
-
-\subsection{Pipe I/O for Unix File Descriptors}
-
-This is a minor feature, but it comes in handy sometimes. In all
-installations of the library, Botan's \type{Pipe} object overloads the
-\keyword{<<} and \keyword{>>} operators for C++ iostream objects,
-which is usually more than sufficient for doing I/O.
-
-However, there are cases where the iostream hierarchy does not map well to
-local 'file types', so there is also the ability to do I/O directly with Unix
-file descriptors. This is most useful when you want to read from or write to
-something like a TCP or Unix-domain socket, or a pipe, since for simple file
-access it's usually easier to just use C++'s file streams.
-
-If \macro{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 \filename{hash\_fd} example, included in the Botan distribution.
-
-\subsection{Entropy Sources}
-
-All of these are used by the \function{Global\_RNG::seed} function if
-they are available. Since this function is called by the
-\type{LibraryInitializer} class when it is created, it is rare
-that you will need to deal with any of these classes directly. Even in
-the case of a long-running server that needs to renew its entropy
-poll, it is easier to call \function{Global\_RNG::seed} (see the
-section entitled ``The Global PRNG'' for more details).
-
-\noindent
-\type{EGD\_EntropySource}: Query an EGD socket. If the macro
-\macro{BOTAN\_EXT\_ENTROPY\_SRC\_EGD} is defined, it can be found in
-\filename{es\_egd.h}. The constructor takes a \type{std::vector<std::string>}
-that specifies the paths to look for an EGD socket.
-
-\noindent
-\type{Unix\_EntropySource}: This entropy source executes programs common on
-Unix systems (such as \filename{uptime}, \filename{vmstat}, and \filename{df})
-and adds it to a buffer. It's quite slow due to process overhead, and (roughly)
-1 bit of real entropy is in each byte that is output. It is declared in
-\filename{es\_unix.h}, if \macro{BOTAN\_EXT\_ENTROPY\_SRC\_UNIX} is
-defined. If you don't have \filename{/dev/urandom} \emph{or} EGD, this is
-probably the thing to use. For a long-running process on Unix, keep on object
-of this type around and run fast polls ever few minutes.
-
-\noindent
-\type{FTW\_EntropySource}: Walk through a filesystem (the root to start
-searching is passed as a string to the constructor), reading files. This tends
-to only be useful on things like \filename{/proc} that have a great deal of
-variability over time, and even then there is only a small amount of entropy
-gathered: about 1 bit of entropy for every 16 bits of output (and many hundreds
-of bits are read in order to get that 16 bits). It is declared in
-\filename{es\_ftw.h}, if \macro{BOTAN\_EXT\_ENTROPY\_SRC\_FTW} is defined. Only
-use this as a last resort. I don't really trust it, and neither should you.
-
-\noindent
-\type{Win32\_CAPI\_EntropySource}: This routines gathers entropy from
-a Win32 CAPI module. It takes an optional \type{std::string} that will
-specify what type of CAPI provider to use. The CAPI RNG is usually a
-default software-based PRNG, but there are a few providers that may
-use a hardware RNG. By default it will use the first provider listed
-in the option ``rng/ms\_capi\_prov\_type'' that is available on the
-machine (currently the providers ``RSA\_FULL'', ``INTEL\_SEC'',
-``FORTEZZA'', and ``RNG'' are recognized).
-
-\noindent
-\type{BeOS\_EntropySource}: Query system statistics using various BeOS-specific
-APIs.
-
-\noindent
-\type{Pthread\_EntropySource}: Attempt to gather entropy based on jitter
-between a number of threads competing for a single mutex. This entropy source
-is \emph{very} slow, and highly questionable in terms of security. However, it
-provides a worst-case fallback on systems that don't have Unix-like features,
-but do support POSIX threads. This module is currently unavailable due to
-problems on some systems.
-
-\subsection{Compressors}
-
-There are two compression algorithms supported by Botan, Zlib and Bzip2 (Gzip
-and Zip encoding will be supported in future releases). Only lossless
-compression algorithms are currently supported by Botan, because they tend to
-be the most useful for cryptography. However, it is very reasonable to consider
-supporting something like GSM speech encoding (which is lossy), for use in
-encrypted voice applications.
-
-You should always compress \emph{before} you encrypt, because encryption seeks
-to hide the redundancy that compression is supposed to try to find and remove.
-
-\subsubsection{Bzip2}
-
-To test for Bzip2, check to see if \macro{BOTAN\_EXT\_COMPRESSOR\_BZIP2} is
-defined. If so, you can include \filename{bzip2.h}, which will declare a pair
-of \type{Filter} objects: \type{Bzip2\_Compression} and
-\type{Bzip2\_Decompression}.
-
-You should be prepared to take an exception when using the decompressing
-filter, for if the input is not valid Bzip2 data, that is what you will
-receive. You can specify the desired level of compression to
-\type{Bzip2\_Compression}'s constructor as an integer between 1 and 9, 1
-meaning worst compression, and 9 meaning the best. The default is to use 9,
-since small values take the same amount of time, just use a little less memory.
-
-The Bzip2 module was contributed by Peter J. Jones.
-
-\subsubsection{Zlib}
-
-Zlib compression works much like Bzip2 compression. The only
-differences in this case are that the macro is
-\macro{BOTAN\_EXT\_COMPRESSOR\_ZLIB}, the header you need to include
-is called \filename{botan/zlib.h} (remember that you shouldn't just
-\verb|#include <zlib.h>|, or you'll get the regular zlib API, which is
-not what you want). The Botan classes for Zlib
-compression/decompression are called \type{Zlib\_Compression} and
-\type{Zlib\_Decompression}.
-
-Like Bzip2, a \type{Zlib\_Decompression} object will throw an exception if
-invalid (in the sense of not being in the Zlib format) data is passed into it.
-
-In the case of zlib's algorithm, a worse compression level will be faster than
-a very high compression ratio. For this reason, the Zlib compressor will
-default to using a compression level of 6. This tends to give a good trade off
-in terms of time spent to compression achieved. There are several factors you
-need to consider in order to decide if you should use a higher compression
-level:
-
-\begin{list}{$\cdot$}
-  \item Better security: the less redundancy in the source text, the harder it
-        is to attack your ciphertext. This is not too much of a concern,
-        because with decent algorithms using sufficiently long keys, it doesn't
-        really matter \emph{that} much (but it certainly can't hurt).
-  \item
-
-  \item Decreasing returns. Some simple experiments by the author showed
-        minimal decreases in the size between level 6 and level 9 compression
-        with large (1 to 3 megabyte) files. There was some difference, but it
-        wasn't that much.
-
-  \item CPU time. Level 9 zlib compression is often two to four times as slow
-        as level 6 compression. This can make a substantial difference in the
-        overall runtime of a program.
-\end{list}
-
-While the zlib compression library uses the same compression algorithm as the
-gzip and zip programs, the format is different. The zlib format is defined in
-RFC 1950.
-
-\subsubsection{Data Sources}
-
-A \type{DataSource} is a simple abstraction for a thing that stores bytes. This
-type is used heavily in the areas of the API related to ASN.1
-encoding/decoding. The following types are \type{DataSource}s: \type{Pipe},
-\type{SecureQueue}, and a couple of special purpose ones:
-\type{DataSource\_Memory} and \type{DataSource\_Stream}.
-
-You can create a \type{DataSource\_Memory} with an array of bytes and a length
-field. The object will make a copy of the data, so you don't have to worry
-about keeping that memory allocated. This is mostly for internal use, but if it
-comes in handy, feel free to use it.
-
-A \type{DataSource\_Stream} is probably more useful than the memory based
-one. Its constructors take either a \type{std::istream} or a
-\type{std::string}. If it's a stream, the data source will use the
-\type{istream} to satisfy read requests (this is particularly useful to use
-with \type{std::cin}). If the string version is used, it will attempt to open
-up a file with that name and read from it.
-
-\subsubsection{Data Sinks}
-
-A \type{DataSink} (in \filename{data\_snk.h}) is a \type{Filter} that
-takes arbitrary amounts of input, and produces no output. This means
-it's doing something with the data outside the realm of what
-\type{Filter}/\type{Pipe} can handle, for example, writing it to a
-file (which is what the \type{DataSink\_Stream} does). There is no
-need for \type{DataSink}s that write to a \type{std::string} or memory
-buffer, because \type{Pipe} can handle that by itself.
-
-Here's a quick example of using a \type{DataSink}, which encrypts
-\filename{in.txt} and sends the output to \filename{out.txt}. There is
-no explicit output operation; the writing of \filename{out.txt} is
-implicit.
-
-\begin{verbatim}
-   DataSource_Stream in("in.txt");
-   Pipe pipe(new CBC_Encryption("Blowfish", "PKCS7", key, iv),
-             new DataSink_Stream("out.txt"));
-   pipe.process_msg(in);
-\end{verbatim}
-
-A real advantage of this is that even if ``in.txt'' is large, only as
-much memory is needed for internal I/O buffers will be used.
-
-\section{Miscellaneous}
-
-This section has documentation for anything that just didn't fit into
-any of the major categories. Many of them (Timers, Allocators) will
-rarely be used in actual application code, but others, like the PBKDF
-algorithms, have a wide degree of applicability.
-
-\subsection{PBKDF Algorithms}
-
-There are various procedures (usually ad-hoc) for turning a
-passphrase into a (mostly) arbitrary length key for a symmetric
-cipher. A general interface for such algorithms is presented in
-\filename{pbkdf.h}. The main function is \function{derive\_key}, which
-takes a passphrase, a salt, an iteration count, and the desired length
-of the output key, and returns a key of that length, deterministically
-produced from the passphrase and salt. If an algorithm can't produce a
-key of that size, it will throw an exception (most notably, PKCS \#5's
-PBKDF1 can only produce strings between 1 and $n$ bytes, where $n$ is
-the output size of the underlying hash function).
-
-The purpose of the iteration count is to make the algorithm take
-longer to compute the final key (reducing the speed of brute-force
-attacks of various kinds). Most standards recommend an iteration count
-of at least 10000. Currently defined PBKDF algorithms are
-``PBKDF1(digest)'', ``PBKDF2(digest)'', and ``OpenPGP-S2K(digest)'';
-you can retrieve any of these using the \function{get\_pbkdf}, found in
-\filename{lookup.h}. As of this writing, ``PBKDF2(SHA-256)'' with
-10000 iterations and a 16 byte salt is recommend for new applications.
-
-\subsubsection{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
-strange manner; instead of specifying how many times to iterate the
-hash, it tells how many \emph{bytes} should be hashed in total
-(including the salt). So the exact iteration count will depend on the
-size of the salt (which is fixed at 8 bytes by the OpenPGP standard,
-though the implementation will allow any salt size) and the size of
-the passphrase.
-
-To get what OpenPGP calls ``Simple S2K'', set iterations to 0, and do
-not specify a salt. To get ``Salted S2K'', again leave the iteration
-count at 0, but give an 8-byte salt. ``Salted and Iterated S2K''
-requires an 8-byte salt and some iteration count (this should be
-significantly larger than the size of the longest passphrase that
-might reasonably be used; somewhere from 1024 to 65536 would probably
-be about right). Using both a reasonably sized salt and a large
-iteration count is highly recommended to prevent password guessing
-attempts.
-
-\subsection{Password Hashing}
-
-Storing passwords for user authentication purposes in plaintext is the
-simplest but least secure method; when an attacker compromises the
-database in which the passwords are stored, they immediately gain
-access to all of them. Often passwords are reused among multiple
-services or machines, meaning once a password to a single service is
-known an attacker has a substantial head start on attacking other
-machines.
-
-The general approach is to store, instead of the password, the output
-of a one way function of the password. Upon receiving an
-authentication request, the authenticator can recompute the one way
-function and compare the value just computed with the one that was
-stored. If they match, then the authentication request succeeds. But
-when an attacker gains access to the database, they only have the
-output of the one way function, not the original password.
-
-Common hash functions such as SHA-256 are one way, but used alone they
-have problems for this purpose. What an attacker can do, upon gaining
-access to such a stored password database, is hash common dictionary
-words and other possible passwords, storing them in a list. Then he
-can search through his list; if a stored hash and an entry in his list
-match, then he has found the password. Even worse, this can happen
-\emph{offline}: an attacker can begin hashing common passwords days,
-months, or years before ever gaining access to the database. In
-addition, if two users choose the same password, the one way function
-output will be the same for both of them, which will be visible upon
-inspection of the database.
-
-There are two solutions to these problems: salting and
-iteration. Salting refers to including, along with the password, a
-randomly chosen value which perturbs the one way function. Salting can
-reduce the effectivness of offline dictionary generation (because for
-each potential password, an attacker would have to compute the one way
-function output for all possible salts - with a large enough salt,
-this can make the problem quite difficult). It also prevents the same
-password from producing the same output, as long as the salts do not
-collide. With a large salt (say 80 to 128 bits) this will be quite
-unlikely. Iteration refers to the general technique of forcing
-multiple one way function evaluations when computing the output, to
-slow down the operation. For instance if hashing a single password
-requires running SHA-256 100,000 times instead of just once, that will
-slow down user authentication by a factor of 100,000, but user
-authentication happens quite rarely, and usually there are more
-expensive operations that need to occur anyway (network and database
-I/O, etc). On the other hand, an attacker who is attempting to break a
-database full of stolen password hashes will be seriously
-inconvenienced by a factor of 100,000 slowdown; they will be able to
-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 a technique called passhash9, in
-\filename{passhash9.h}, which is based on PBKDF2. Two functions are
-provided in this header, \function{generate\_passhash9} and
-\function{check\_passhash9}.  The generate function takes the password
-to hash, a \type{RandomNumberGenerator}, 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.
-The check function 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).
-An example can be found in \filename{doc/examples/passhash.cpp}.
-
-Passhash9 currently uses HMAC(SHA-1) for the underlying PBKDF2
-psuedo-random function, but can be extended to use different
-algorithms in the future if necessary. For instance using a PRF based
-on Blowfish (a block cipher that requires 4 KiB of RAM for efficient
-execution) could be used to make hardware-based password cracking more
-expensive (this was one motivation for Blowfish's use in the bcrypt
-hashing scheme, in fact).
-
-\subsection{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.
-
-\subsection{Exceptions}
-
-Sooner or later, something is going to go wrong. Botan's behavior when
-something unusual occurs, like most C++ software, is to throw an exception.
-Exceptions in Botan are derived from the \type{Exception} class. You can see
-most of the major varieties of exceptions used in Botan by looking at
-\filename{exceptn.h}. The only function you really need to concern yourself
-with is \type{const char*} \function{what()}. This will return an error message
-relevant to the error that occurred. For example:
-
-\begin{verbatim}
-try {
-   // various Botan operations
-   }
-catch(Botan::Exception& e)
-   {
-   cout << "Botan exception caught: " << e.what() << endl;
-   // error handling, or just abort
-   }
-\end{verbatim}
-
-Botan's exceptions are derived from \type{std::exception}, so you don't need
-to explicitly check for Botan exceptions if you're already catching the ISO
-standard ones.
-
-\subsection{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 \texttt{mux\_pthr} module, implementing the \type{Mutex} interface for
-systems that have POSIX threads.
-
-If your application is using threads, you \emph{must} add the option
-``thread\_safe'' to the options string when you create the
-\type{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.
-
-\subsection{Secure Memory}
-
-A major concern with mixing modern multiuser OSes and cryptographic
-code is that at any time the code (including secret keys) could be
-swapped to disk, where it can later be read by an attacker. Botan
-stores almost everything (and especially anything sensitive) in memory
-buffers that a) clear out their contents when their destructors are
-called, and b) have easy plugins for various memory locking functions,
-such as the \function{mlock}(2) call on many Unix systems.
-
-Two of the allocation method used (``malloc'' and ``mmap'') don't
-require any extra privileges on Unix, but locking memory does. At
-startup, each allocator type will attempt to allocate a few blocks
-(typically totaling 128k), so if you want, you can run your
-application \texttt{setuid} \texttt{root}, and then drop privileges
-immediately after creating your \type{LibraryInitializer}. If you end
-up using more than what's been allocated, some of your sensitive data
-might end up being swappable, but that beats running as \texttt{root}
-all the time.
-
-These classes should also be used within your own code for storing
-sensitive data. They are only meant for primitive data types (int,
-long, etc): if you want a container of higher level Botan objects, you
-can just use a \verb|std::vector|, since these objects know how to
-clear themselves when they are destroyed. You cannot, however, have a
-\verb|std::vector| (or any other container) of \type{Pipe}s or
-\type{Filter}s, because these types have pointers to other
-\type{Filter}s, and implementing copy constructors for these types
-would be both hard and quite expensive (vectors of pointers to such
-objects is fine, though).
-
-These types are not described in any great detail: for more information,
-consult the definitive sources~--~the header files \filename{secmem.h} and
-\filename{allocate.h}.
-
-\type{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 \function{clear()}, and
-\type{u32bit} \function{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: \verb|SecureBuffer<byte, 8> key;|).
-
-\type{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 \type{SecureBuffer}, it implements \function{clear}
-and \function{size}.
-
-\subsection{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 \filename{allocate.h}. Code needing
-to allocate or deallocate memory calls \function{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
-\function{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 \type{Default\_Allocator}, which
-just allocates memory using \function{malloc}, and \function{memset}s it to 0
-when the memory is released. It is known by the name ``malloc''. If you ask for
-another type of allocator (``locking'' and ``mmap'' are currently used), and it
-is not available, some other allocator will be returned.
-
-You can add in a new allocator type using \function{add\_allocator\_type}. This
-function takes a string and a pointer to an allocator. The string gives this
-allocator type a name to which it can be referred when one is requesting it
-with \function{get\_allocator}. If an error occurs (such as the name being
-already registered), this function returns false. It will return true if the
-allocator was successfully registered. If you ask it to,
-\type{LibraryInitializer} will do this for you.
-
-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.
-
-\subsection{BigInt}
-
-\type{BigInt} is Botan's implementation of a multiple-precision
-integer. Thanks to C++'s operator overloading features, using \type{BigInt} is
-often quite similar to using a native integer type. The number of functions
-related to \type{BigInt} is quite large. You can find most of them in
-\filename{bigint.h} and \filename{numthry.h}.
-
-Due to the sheer number of functions involved, only a few, which a regular user
-of the library might have to deal with, are mentioned here. Fully documenting
-the MPI library would take a significant while, so if you need to use it now,
-the best way to learn is to look at the headers.
-
-Probably the most important are the encoding/decoding functions, which
-transform the normal representation of a \type{BigInt} into some other form,
-such as a decimal string.
-
-\type{SecureVector<byte>} \function{BigInt::encode}(\type{BigInt},
-\type{Encoding})
-
-\noindent
-and
-
-\type{BigInt} \function{BigInt::decode}(\type{SecureVector<byte>},
-\type{Encoding})
-
-\type{Encoding} is an enum that has values \type{Binary}, \type{Octal},
-\type{Decimal}, and \type{Hexadecimal}. The parameter will default to
-\type{Binary}. These functions are static member functions, so they would be
-called like this:
-
-\begin{verbatim}
-  BigInt n1; // some number
-  SecureVector<byte> n1_encoded = BigInt::encode(n1);
-  BigInt n2 = BigInt::decode(n1_encoded);
-  // now n1 == n2
-\end{verbatim}
-
-There are also C++-style I/O operators defined for use with \type{BigInt}. The
-input operator understands negative numbers, hexadecimal numbers (marked with a
-leading ``0x''), and octal numbers (marked with a leading '0'). The '-' must
-come before the ``0x'' or '0' marker. The output operator will never adorn the
-output; for example, when printing a hexadecimal number, there will not be a
-leading ``0x'' (though a leading '-' will be printed if the number is
-negative). If you want such things, you'll have to do them yourself.
-
-\type{BigInt} has constructors that can create a \type{BigInt} from an unsigned
-integer or a string. You can also decode a \type{byte}[] / length pair into a
-BigInt. There are several other \type{BigInt} constructors, which I would
-seriously recommend you avoid, as they are only intended for use internally by
-the library, and may arbitrarily change, or be removed, in a future release.
-
-An random sampling of \type{BigInt} related functions:
-
-\type{u32bit} \function{BigInt::bytes}(): Return the size of this \type{BigInt}
-in bytes.
-
-\type{BigInt} \function{random\_prime(\type{u32bit} \arg{b})}: Return a prime
-number \arg{b} bits long.
-
-\type{BigInt} \function{gcd}(\type{BigInt} \arg{x}, \type{BigInt} \arg{y}):
-Returns the greatest common divisor of \arg{x} and \arg{y}. Uses the binary
-GCD algorithm.
-
-\type{bool} \function{is\_prime}(\type{BigInt} \arg{x}): Returns true if
-\arg{x} is a (possible) prime number. Uses the Miller-Rabin probabilistic
-primality test with fixed bases. For higher assurance, use
-\function{verify\_prime}, which uses more rounds and randomized 48-bit bases.
-
-\subsubsection{Efficiency Hints}
-
-If you can, always use expressions of the form \verb|a += b| over
-\verb|a = a + b|. The difference can be \emph{very} substantial,
-because the first form prevents at least one needless memory
-allocation, and possibly as many as three.
-
-If you're doing repeated modular exponentiations with the same modulus, create
-a \type{BarrettReducer} ahead of time. If the exponent or base is a constant,
-use the classes in \filename{mod\_exp.h}. This stuff is all handled for you by
-the normal high-level interfaces, of course.
-
-Never use the low-level MPI functions (those that begin with
-\texttt{bigint\_}). These are completely internal to the library, and
-may make arbitrarily strange and undocumented assumptions about their
-inputs, and don't check to see if they are true, on the assumption
-that only the library itself calls them, and that the library knows
-what the assumptions are. The interfaces for these functions can
-change completely without notice.
-
-\section{Algorithms}
-
-\subsection{Recommended Algorithms}
-
-This section is by no means the last word on selecting which
-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
-were evaluated when making this list: security, standardization,
-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.
-
-\begin{list}{$\cdot$}
-  \item Block ciphers: AES or Serpent in CBC, CTR, or XTS mode
-
-  \item Hash functions: SHA-256, SHA-512
-
-  \item MACs: HMAC with any recommended hash function
-
-  \item Public Key Encryption: RSA with ``EME1(SHA-256)''
-
-  \item Public Key Signatures: RSA with EMSA4 and any recommended
-    hash, or DSA or ECDSA with ``EMSA1(SHA-256)''
-
-  \item Key Agreement: Diffie-Hellman or ECDH, with ``KDF2(SHA-256)''
-\end{list}
-
-\subsection{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
-to use them. However, you do need to know what string (or strings) are
-used to identify that algorithm. These names conform to those set out
-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
-\url{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,
-etc). These are shown in the following list; all of them default to
-reasonable values. There are algorithm-specific limits on most of
-them. When you see something like ``HASH'' or ``BLOCK'', that means
-you should insert the name of some algorithm of that type. There are
-no defaults for those options.
-
-A few very obscure algorithms are skipped; if you need one of them,
-you'll know it, and you can look in the appropriate header to see what
-that classes' \function{name} function returns (the names tend to
-match that in SCAN, if it's defined there).
-
-\begin{list}{$\cdot$}
-  \item ROUNDS: The number of rounds in a block cipher.
-  \item
-  \item OUTSZ: The output size of a hash function or MAC
-\end{list}
-
-\vskip .05in
-\noindent
-\textbf{Block Ciphers:} ``AES'' (and ``AES-128'', ``AES-192'', and
-``AES-256''), ``Blowfish'', ``CAST-128'', ``CAST-256'', ``DES'',
-``DESX'', ``TripleDES'', ``GOST-28147-89'', ``IDEA'', ``KASUMI'',
-``MARS'', ``MISTY1(ROUNDS)'', ``Noekeon'', ``RC2'', ``RC5(ROUNDS)'',
-``RC6'', ``SAFER-SK(ROUNDS)'', ``SEED'', ``Serpent'', ``Skipjack'',
-``Square'', ``TEA'', ``Twofish'', ``XTEA''
-
-\noindent
-\textbf{Stream Ciphers:} ``ARC4'', ``MARK4'', ``Salsa20'', ``Turing'',
-``WiderWake4+1-BE''
-
-\noindent
-\textbf{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''
-
-\noindent
-\textbf{MACs:} ``HMAC(HASH)'', ``CMAC(BLOCK)'', ``X9.19-MAC''
-
-\section{Support and Further Information}
-
-\subsection{Patents}
-
-Some of the algorithms implemented by Botan may be covered by patents in some
-locations. Algorithms known to have patent claims on them in the United States
-and that are not available in a license-free/royalty-free manner include:
-IDEA, MISTY1, RC5, RC6, and Nyberg-Rueppel.
-
-You must not assume that, just because an algorithm is not listed here, it is
-not encumbered by patents. If you have any concerns about the patent status of
-any algorithm you are considering using in an application, please discuss it
-with your attorney.
-
-\subsection{Support}
-
-Questions or problems you have with Botan can be directed to the
-development mailing list. Joining this list is highly recommended if
-you're going to be using Botan, since often advance notice of upcoming
-changes is sent there. ``Philosophical'' bug reports, announcements of
-programs using Botan, and anything else having to do with Botan are
-also welcome.
-
-The lists can be found at
-\url{http://lists.randombit.net/mailman/listinfo/}.
-
-\subsection{Contact Information}
-
-A PGP key with a fingerprint of
-\verb|621D AF64 11E1 851C 4CF9 A2E1 6211 EBF1 EFBA DFBC| is used to sign all
-Botan releases. This key can be found in the file \filename{doc/pgpkeys.txt};
-PGP keys for the developers are also stored there.
-
-\vskip 5pt \noindent
-Web Site: \url{http://botan.randombit.net}
-
-\subsection{License}
-
-Copyright \copyright  2000-2010, Jack Lloyd
-
-Licensed under the same terms as the Botan source
-
-\end{document}
diff --git a/doc/bigint.txt b/doc/bigint.txt
new file mode 100644
index 000000000..1cdc685d3
--- /dev/null
+++ b/doc/bigint.txt
@@ -0,0 +1,64 @@
+BigInt
+========================================
+
+``BigInt`` is Botan's implementation of a multiple-precision
+integer. Thanks to C++'s operator overloading features, using ``BigInt`` is
+often quite similar to using a native integer type. The number of functions
+related to ``BigInt`` is quite large. You can find most of them in
+``botan/bigint.h`` and ``botan/numthry.h``.
+
+Probably the most important are the encoding/decoding functions, which
+transform the normal representation of a ``BigInt`` into some other
+form, such as a decimal string.
+
+.. cpp:function:: SecureVector<byte> BigInt::encode(const BigInt& n, Encoding enc = Binary)
+
+  This function encodes the BigInt n into a memory
+  vector. ``Encoding`` is an enum that has values ``Binary``,
+  ``Octal``, ``Decimal``, and ``Hexadecimal``.
+
+.. cpp:function:: BigInt BigInt::decode(const MemoryRegion<byte>& vec, Encoding enc)
+
+  Decode the integer from ``vec`` using the encoding specified.
+
+These functions are static member functions, so they would be called
+like this::
+
+  BigInt n1 = ...; // some number
+  SecureVector<byte> n1_encoded = BigInt::encode(n1);
+  BigInt n2 = BigInt::decode(n1_encoded);
+  assert(n1 == n2);
+
+There are also C++-style I/O operators defined for use with
+``BigInt``. The input operator understands negative numbers,
+hexadecimal numbers (marked with a leading "0x"), and octal numbers
+(marked with a leading '0'). The '-' must come before the "0x" or '0'
+marker. The output operator will never adorn the output; for example,
+when printing a hexadecimal number, there will not be a leading "0x"
+(though a leading '-' will be printed if the number is negative). If
+you want such things, you'll have to do them yourself.
+
+``BigInt`` has constructors that can create a ``BigInt`` from an
+unsigned integer or a string. You can also decode an array (a ``byte``
+pointer plus a length) into a ``BigInt`` using a constructor.
+
+Efficiency Hints
+----------------------------------------
+
+If you can, always use expressions of the form ``a += b`` over
+``a = a + b``. The difference can be *very* substantial,
+because the first form prevents at least one needless memory
+allocation, and possibly as many as three.
+
+If you're doing repeated modular exponentiations with the same modulus, create
+a ``BarrettReducer`` ahead of time. If the exponent or base is a constant,
+use the classes in ``mod_exp.h``. This stuff is all handled for you by
+the normal high-level interfaces, of course.
+
+Never use the low-level MPI functions (those that begin with
+``bigint_``). These are completely internal to the library, and
+may make arbitrarily strange and undocumented assumptions about their
+inputs, and don't check to see if they are true, on the assumption
+that only the library itself calls them, and that the library knows
+what the assumptions are. The interfaces for these functions can
+change completely without notice.
diff --git a/doc/building.tex b/doc/building.tex
deleted file mode 100644
index 7164f74eb..000000000
--- a/doc/building.tex
+++ /dev/null
@@ -1,444 +0,0 @@
-\documentclass{article}
-
-\setlength{\textwidth}{6.5in}
-\setlength{\textheight}{9in}
-
-\setlength{\headheight}{0in}
-\setlength{\topmargin}{0in}
-\setlength{\headsep}{0in}
-
-\setlength{\oddsidemargin}{0in}
-\setlength{\evensidemargin}{0in}
-
-\title{\textbf{Botan Build Guide}}
-\author{Jack Lloyd \\
-        \texttt{[email protected]}}
-\date{2010-06-10}
-
-\newcommand{\filename}[1]{\texttt{#1}}
-\newcommand{\module}[1]{\texttt{#1}}
-
-\newcommand{\type}[1]{\texttt{#1}}
-\newcommand{\function}[1]{\textbf{#1}}
-\newcommand{\macro}[1]{\texttt{#1}}
-
-\begin{document}
-
-\maketitle
-
-\tableofcontents
-
-\parskip=5pt
-\pagebreak
-
-\section{Introduction}
-
-This document describes how to build Botan on Unix/POSIX and MS
-Windows systems. The POSIX oriented descriptions should apply to most
-common Unix systems (including MacOS X), along with POSIX-ish systems
-like BeOS, QNX, and Plan 9. Currently, systems other than Windows and
-POSIX (such as VMS, MacOS 9, OS/390, OS/400, ...) are not supported by
-the build system, primarily due to lack of access. Please contact the
-maintainer if you would like to build Botan on such a system.
-
-Botan's build is controlled by configure.py, which is a Python
-script. Python 2.5 or later is required. If you want to use the
-(incompatible) Python 3, you must first run the \texttt{2to3} script
-on it.
-
-\section{For the Impatient}
-
-\begin{verbatim}
-$ ./configure.py [--prefix=/some/directory]
-$ make
-$ make check
-$ make install
-\end{verbatim}
-
-Or using \verb|nmake|, if you're compiling on Windows with Visual
-C++. On platforms that do not understand the '\#!' convention for
-beginning script files, or that have Python installed in an unusual
-spot, you might need to prefix the \texttt{configure.py} command with
-\texttt{python} or \texttt{/path/to/python}.
-
-\section{Building the Library}
-
-The first step is to run \filename{configure.py}, which is a Python
-script that creates various directories, config files, and a Makefile
-for building everything. The script requires at least Python 2.5; any
-later version of Python 2.x should also work. Python 3.1 will also
-work but requires an extra step, see the section ``Using Python 3.1'',
-later in this document.
-
-The script will attempt to guess what kind of system you are trying
-to compile for (and will print messages telling you what it guessed).
-You can override this process by passing the options \verb|--cc|,
-\verb|--os|, and \verb|--cpu|.
-
-You can pass basically anything reasonable with \verb|--cpu|: the
-script knows about a large number of different architectures, their
-sub-models, and common aliases for them. You should only select the
-64-bit version of a CPU (such as ``sparc64'' or ``mips64'') if your
-operating system knows how to handle 64-bit object code -- a 32-bit
-kernel on a 64-bit CPU will generally not like 64-bit code.
-
-By default the script tries to figure out what will work on your
-system, and use that. It will print a display at the end showing which
-algorithms have and have not been enabled. For instance on one system
-we might see lines like:
-
-\begin{verbatim}
- INFO: Skipping mod because CPU incompatible - asm_amd64 mp_amd64 mp_asm64 sha1_amd64
- INFO: Skipping mod because OS incompatible - cryptoapi_rng win32_stats
- INFO: Skipping mod because compiler incompatible - mp_ia32_msvc
- INFO: Skipping mod because loaded on request only - bzip2 gnump openssl qt_mutex zlib
-\end{verbatim}
-
-The ones that are 'loaded on request only' have to be explicitly asked
-for, because they rely on third party libraries which your system
-might not have. For instance to enable zlib support, add
-\verb|--with-zlib| to your invocation of \verb|configure.py|.
-
-You can control which algorithms and modules are built using the
-options \verb|--enable-modules=MODS| and
-\verb|--disable-modules=MODS|, for instance
-\verb|--enable-modules=zlib| and \verb|--disable-modules=rc5,idea|.
-Modules not listed on the command line will simply be loaded if needed
-or if configured to load by default. If you use \verb|--no-autoload|,
-only the most core modules will be included; you can then explicitly
-enable things that you want to use with enable-modules. This is useful
-for creating a minimal build targetted to a specific application.
-
-The script tries to guess what kind of makefile to generate, and it
-almost always guesses correctly (basically, Visual C++ uses NMAKE with
-Windows commands, and everything else uses Unix make with POSIX
-commands). Just in case, you can override it with
-\verb|--make-style=somestyle|. The styles Botan currently knows about
-are 'unix' (normal Unix makefiles), and 'nmake', the make variant
-commonly used by Windows compilers. To add a new variant (eg, a build
-script for VMS), you will need to create a new template file in
-\filename{src/build-data/makefile}.
-
-\subsection{POSIX / Unix}
-
-The basic build procedure on Unix and Unix-like systems is:
-
-\begin{verbatim}
-   $ ./configure.py [--enable-modules=<list>] [--cc=CC]
-   $ make
-   # You may need to set your LD_LIBRARY_PATH or equivalent for ./check to run
-   $ make check # optional, but a good idea
-   $ make install
-\end{verbatim}
-
-On Unix systems the script will default to using GCC; use
-\texttt{--cc} if you want something else. For instance use
-\texttt{--cc=icc} for Intel C++ and \texttt{--cc=clang} for Clang.
-
-The \verb|make install| target has a default directory in which it
-will install Botan (typically \verb|/usr/local|). You can override
-this by using the \texttt{--prefix} argument to
-\filename{configure.py}, like so:
-
-\verb|./configure.py --prefix=/opt <other arguments>|
-
-On some systems shared libraries might not be immediately visible to
-the runtime linker. For example, on Linux you may have to edit
-\filename{/etc/ld.so.conf} and run \texttt{ldconfig} (as root) in
-order for new shared libraries to be picked up by the linker. An
-alternative is to set your \texttt{LD\_LIBRARY\_PATH} shell variable
-to include the directory that the Botan libraries were installed into.
-
-\subsection{Mac OS X}
-
-In general the Unix instructions above should apply, however OS X does
-not support \texttt{LD\_LIBRARY\_PATH}. Thomas Keller suggests instead
-running \verb|install_name_tool| between building and running the
-self-test program:
-
-\begin{verbatim}
-  $ VERSION=1.9.10
-  $ install_name_tool -change $(otool -X -D libbotan-$VERSION.dylib) \
-       $PWD/libbotan-$VERSION.dylib check
-\end{verbatim}
-
-\subsection{MS Windows}
-
-If you don't want to deal with building botan on Windows, check the
-website; commonly prebuilt Windows binaries with installers are
-available, especially for stable versions.
-
-You need to have a copy of Python installed, and have both Python and
-your chosen compiler in your path. Open a command shell (or the SDK
-shell), and run:
-
-\begin{verbatim}
-   > python configure.py --cc=msvc (or --cc=gcc for MinGW) [--cpu=CPU]
-   > nmake
-   > nmake check # optional, but recommended
-   > nmake install
-\end{verbatim}
-
-For Win95 pre OSR2, the \verb|cryptoapi_rng| module will not work,
-because CryptoAPI didn't exist. And all versions of NT4 lack the
-ToolHelp32 interface, which is how \verb|win32_stats| does its slow
-polls, so a version of the library built with that module will not
-load under NT4. Later versions of Windows support both methods, so
-this shouldn't be much of an issue anymore.
-
-By default the install target will be 'C:\textbackslash botan'; you
-can modify this with the \texttt{--prefix} option.
-
-When building your applications, all you have to do is tell the
-compiler to look for both include files and library files in
-\verb|C:\botan|, and it will find both. Or you can move them to a
-place where they will be in the default compiler search paths (consult
-your documentation and/or local expert for details).
-
-\section{Trickier Things}
-
-\subsection{Modules Relying on Third Party Libraries}
-
-There are a fairly large number of modules included with Botan. Some
-of these are extremely useful, while others are only necessary in very
-unusual circumstances. Most are loaded (or not) automatically as
-necessary, but some require external libraries are thus must be
-enabled at build time; these include:
-
-\newcommand{\mod}[2]{\textbf{#1}: #2}
-
-\begin{list}{$\cdot$}
-  \item \mod{bzip2}{Enables an application to perform bzip2
-    compression and decompression using the library. Available on any
-    system that has bzip2. To enable, use option \texttt{--with-bzip2}}
-
-  \item \mod{zlib}{Enables an application to perform zlib compression
-    and decompression using the library. Available on any system that
-    has zlib. To enable, use option \texttt{--with-zlib}}
-
-  \item \mod{gnump}{An engine that uses GNU MP to speed up PK
-    operations.  GNU MP 4.1 or later is required.  To enable, use
-    option \texttt{--with-gnump}}
-
-  \item \mod{openssl}{An engine that uses OpenSSL to speed up public
-    key operations and some ciphers/hashes. OpenSSL 0.9.7 or later is
-    required. Note that, unlike GNU MP, OpenSSL's versions are not
-    always faster than the versions built into botan. To enable, use
-    option \texttt{--with-openssl}}
-
-\end{list}
-
-\subsection{Amalgamation}
-
-You can also configure Botan to be built using only a single source
-file; this is quite convenient if you plan to embed the library into
-another application. To do so, run \filename{configure.py} with
-whatever arguments you would ordinarily use, along with the option
-\texttt{--gen-amalgamation}. This will create two (rather large)
-files, \filename{botan\_all.h} and \filename{botan\_all.cpp}.
-
-Whenever you would have included a botan header, you can then include
-\filename{botan\_all.h}, and include \filename{botan\_all.cpp} along
-with the rest of the source files in your build. If you want to be
-able to easily switch between amalgamated and non-amalgamated versions
-(for instance to take advantage of prepackaged versions of botan on
-operating systems that support it), you can instead ignore
-\filename{botan\_all.h} and use the headers from
-\filename{build/include} as normal.
-
-\subsection{Multiple Builds}
-
-It may be useful to run multiple builds with different
-configurations. Specify \verb|--build-dir=<dir>| to set up a build
-environment in a different directory.
-
-\subsection{Using Python 3.1}
-
-The versions of Python begininning with 3 are (intentionally)
-incompatible with the (currently more common) 2.x series. If you want
-to use Python 3.1 to set up the build, you'll have to use the
-\texttt{2to3} program (included in the Python distribution) on the
-script; this will convert the script to the Python 3.x dialect:
-
-\begin{verbatim}
-  $ python ./configure.py
-  File "configure.py", line 860
-    except KeyError, e:
-                   ^
-SyntaxError: invalid syntax
-  $ # incompatible python version, let's fix it
-  $ 2to3 -w configure.py
-[...]
-RefactoringTool: Files that were modified:
-RefactoringTool: configure.py
-  $ python ./configure.py
-[...]
-\end{verbatim}
-
-\subsection{Local Configuration}
-
-You may want to do something peculiar with the configuration; to
-support this there is a flag to \filename{configure.py} called
-\texttt{--with-local-config=<file>}. The contents of the file are
-inserted into \filename{build/build.h} which is (indirectly) included
-into every Botan header and source file.
-
-\subsection{Configuration Parameters}
-
-There are some configuration parameters which you may want to tweak
-before building the library. These can be found in
-\filename{config.h}. This file is overwritten every time the configure
-script is run (and does not exist until after you run the script for
-the first time).
-
-Also included in \filename{build/build.h} are macros which are defined
-if one or more extensions are available. All of them begin with
-\verb|BOTAN_HAS_|. For example, if \verb|BOTAN_HAS_COMPRESSOR_BZIP2|
-is defined, then an application using Botan can include
-\filename{<botan/bzip2.h>} and use the Bzip2 filters.
-
-\macro{BOTAN\_MP\_WORD\_BITS}: This macro controls the size of the
-words used for calculations with the MPI implementation in Botan. You
-can choose 8, 16, 32, or 64, with 32 being the default. You can use 8,
-16, or 32 bit words on any CPU, but the value should be set to the
-same size as the CPU's registers for best performance. You can only
-use 64-bit words if an assembly module (such as \module{mp\_ia32} or
-\module{mp\_asm64}) is used. If the appropriate module is available,
-64 bits are used, otherwise this is set to 32. Unless you are building
-for a 8 or 16-bit CPU, this isn't worth messing with.
-
-\macro{BOTAN\_VECTOR\_OVER\_ALLOCATE}: The memory container
-\type{SecureVector} will over-allocate requests by this amount (in
-elements). In several areas of the library, we grow a vector fairly often. By
-over-allocating by a small amount, we don't have to do allocations as often
-(which is good, because the allocators can be quite slow). If you \emph{really}
-want to reduce memory usage, set it to 0. Otherwise, the default should be
-perfectly fine.
-
-\macro{BOTAN\_DEFAULT\_BUFFER\_SIZE}: This constant is used as the size of
-buffers throughout Botan. A good rule of thumb would be to use the page size of
-your machine. The default should be fine for most, if not all, purposes.
-
-\section{Building Applications}
-
-\subsection{Unix}
-
-Botan usually links in several different system libraries (such as
-\texttt{librt} and \texttt{libz}), depending on which modules are
-configured at compile time. In many environments, particularly ones
-using static libraries, an application has to link against the same
-libraries as Botan for the linking step to succeed. But how does it
-figure out what libraries it \emph{is} linked against?
-
-The answer is to ask the \filename{botan-config} script. This
-basically solves the same problem all the other \filename{*-config}
-scripts solve, and in basically the same manner.
-
-There are 4 options:
-
-\texttt{--prefix[=DIR]}: If no argument, print the prefix where Botan
-is installed (such as \filename{/opt} or \filename{/usr/local}). If an
-argument is specified, other options given with the same command will
-execute as if Botan as actually installed at \filename{DIR} and not
-where it really is; or at least where \filename{botan-config} thinks
-it really is. I should mention that it
-
-\texttt{--version}: Print the Botan version number.
-
-\texttt{--cflags}: Print options that should be passed to the compiler
-whenever a C++ file is compiled. Typically this is used for setting
-include paths.
-
-\texttt{--libs}: Print options for which libraries to link to (this includes
-\texttt{-lbotan}).
-
-Your \filename{Makefile} can run \filename{botan-config} and get the
-options necessary for getting your application to compile and link,
-regardless of whatever crazy libraries Botan might be linked against.
-
-Botan also by default installs a file for \texttt{pkg-config},
-namespaced by the major and minor versions. So it can be used,
-for instance, as
-
-\begin{verbatim}
-$ pkg-config botan-1.9 --modversion
-1.9.8
-$ pkg-config botan-1.9 --cflags
--I/usr/local/include
-$ pkg-config botan-1.9 --libs
--L/usr/local/lib -lbotan -lm -lbz2 -lpthread -lrt
-\end{verbatim}
-
-\subsection{MS Windows}
-
-No special help exists for building applications on Windows. However,
-given that typically Windows software is distributed as binaries, this
-is less of a problem - only the developer needs to worry about it. As
-long as they can remember where they installed Botan, they just have
-to set the appropriate flags in their Makefile/project file.
-
-\section{Language Wrappers}
-
-\subsection{Building the Python wrappers}
-
-The Python wrappers for Botan use Boost.Python, so you must have Boost
-installed. To build the wrappers, add the flag
-
-\verb|--with-boost-python|
-
-to \verb|configure.py|. This will create a second makefile,
-\verb|Makefile.python|, with instructions for building the Python
-module. After building the library, execute
-
-\begin{verbatim}
-$ make -f Makefile.python
-\end{verbatim}
-
-to build the module. Currently only Unix systems are supported, and
-the Makefile assumes that the version of Python you want to build
-against is the same one you used to run \verb|configure.py|.
-
-To install the module, use the \verb|install| target.
-
-Examples of using the Python module can be seen in \filename{doc/python}
-
-\subsection{Building the Perl XS wrappers}
-
-To build the Perl XS wrappers, change your directory to
-\filename{src/wrap/perl-xs} and run \verb|perl Makefile.PL|, then run
-\verb|make| to build the module and \verb|make test| to run the test
-suite.
-
-\begin{verbatim}
-$ perl Makefile.PL
-Checking if your kit is complete...
-Looks good
-Writing Makefile for Botan
-$ make
-cp Botan.pm blib/lib/Botan.pm
-AutoSplitting blib/lib/Botan.pm (blib/lib/auto/Botan)
-/usr/bin/perl5.8.8 /usr/lib64/perl5/5.8.8/ExtUtils/xsubpp  [...]
-g++ -c   -Wno-write-strings -fexceptions  -g   [...]
-Running Mkbootstrap for Botan ()
-chmod 644 Botan.bs
-rm -f blib/arch/auto/Botan/Botan.so
-g++  -shared Botan.o  -o blib/arch/auto/Botan/Botan.so  \
-           -lbotan -lbz2 -lpthread -lrt -lz     \
-
-chmod 755 blib/arch/auto/Botan/Botan.so
-cp Botan.bs blib/arch/auto/Botan/Botan.bs
-chmod 644 blib/arch/auto/Botan/Botan.bs
-Manifying blib/man3/Botan.3pm
-$ make test
-PERL_DL_NONLAZY=1 /usr/bin/perl5.8.8 [...]
-t/base64......ok
-t/filt........ok
-t/hex.........ok
-t/oid.........ok
-t/pipe........ok
-t/x509cert....ok
-All tests successful.
-Files=6, Tests=83,  0 wallclock secs ( 0.08 cusr +  0.02 csys =  0.10 CPU)
-\end{verbatim}
-
-\end{document}
diff --git a/doc/building.txt b/doc/building.txt
new file mode 100644
index 000000000..2e52eee1c
--- /dev/null
+++ b/doc/building.txt
@@ -0,0 +1,403 @@
+
+Building Botan
+=================================
+
+This document describes how to build Botan on Unix/POSIX and MS
+Windows systems. The POSIX oriented descriptions should apply to most
+common Unix systems (including MacOS X), along with POSIX-ish systems
+like BeOS, QNX, and Plan 9. Currently, systems other than Windows and
+POSIX (such as VMS, MacOS 9, OS/390, OS/400, ...) are not supported by
+the build system, primarily due to lack of access. Please contact the
+maintainer if you would like to build Botan on such a system.
+
+Botan's build is controlled by configure.py, which is a `Python
+<http://www.python.org>`_ script. Python 2.5 or later is required.
+
+For the impatient, this works for most systems::
+
+  $ ./configure.py [--prefix=/some/directory]
+  $ make
+  $ make check
+  $ make install
+
+Or using ``nmake``, if you're compiling on Windows with Visual C++. On
+platforms that do not understand the '#!' convention for beginning
+script files, or that have Python installed in an unusual spot, you
+might need to prefix the ``configure.py`` command with ``python`` or
+``/path/to/python``::
+
+  $ python ./configure.py [arguments]
+
+Configuring the Build
+---------------------------------
+
+The first step is to run ``configure.py``, which is a Python script
+that creates various directories, config files, and a Makefile for
+building everything. The script requires at least Python 2.5; any
+later version of Python 2.x should also work. Python 3.1 will also
+work but requires an extra step; see :ref:`configure_with_python3` for
+details.
+
+The script will attempt to guess what kind of system you are trying to
+compile for (and will print messages telling you what it guessed).
+You can override this process by passing the options ``--cc``,
+``--os``, and ``--cpu``.
+
+You can pass basically anything reasonable with ``--cpu``: the script
+knows about a large number of different architectures, their
+sub-models, and common aliases for them. You should only select the
+64-bit version of a CPU (such as "sparc64" or "mips64") if your
+operating system knows how to handle 64-bit object code - a 32-bit
+kernel on a 64-bit CPU will generally not like 64-bit code.
+
+By default the script tries to figure out what will work on your
+system, and use that. It will print a display at the end showing which
+algorithms have and have not been enabled. For instance on one system
+we might see lines like::
+
+ INFO: Skipping mod because CPU incompatible - asm_amd64 mp_amd64 mp_asm64 sha1_amd64
+ INFO: Skipping mod because OS incompatible - cryptoapi_rng win32_stats
+ INFO: Skipping mod because compiler incompatible - mp_ia32_msvc
+ INFO: Skipping mod because loaded on request only - bzip2 gnump openssl qt_mutex zlib
+
+The ones that are 'loaded on request only' have to be explicitly asked
+for, because they rely on third party libraries which your system
+might not have. For instance to enable zlib support, add
+``--with-zlib`` to your invocation of ``configure.py``.
+
+You can control which algorithms and modules are built using the
+options ``--enable-modules=MODS`` and ``--disable-modules=MODS``, for
+instance ``--enable-modules=zlib`` and ``--disable-modules=rc5,idea``.
+Modules not listed on the command line will simply be loaded if needed
+or if configured to load by default. If you use ``--no-autoload``,
+only the most core modules will be included; you can then explicitly
+enable things that you want to use with ``--enable-modules``. This is
+useful for creating a minimal build targetted to a specific
+application, especially in conjuction with the amalgamation option;
+see :ref:`amalgamation`.
+
+The script tries to guess what kind of makefile to generate, and it
+almost always guesses correctly (basically, Visual C++ uses NMAKE with
+Windows commands, and everything else uses Unix make with POSIX
+commands). Just in case, you can override it with
+``--make-style=somestyle``. The styles Botan currently knows about are
+'unix' (normal Unix makefiles), and 'nmake', the make variant commonly
+used by Windows compilers. To add a new variant (eg, a build script
+for VMS), you will need to create a new template file in
+``src/build-data/makefile``.
+
+On Unix
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The basic build procedure on Unix and Unix-like systems is::
+
+   $ ./configure.py [--enable-modules=<list>] [--cc=CC]
+   $ make
+   # You may need to set your LD_LIBRARY_PATH or equivalent for ./check to run
+   $ make check # optional, but a good idea
+   $ make install
+
+On Unix systems the script will default to using GCC; use
+``--cc`` if you want something else. For instance use
+``--cc=icc`` for Intel C++ and ``--cc=clang`` for Clang.
+
+The ``make install`` target has a default directory in which it
+will install Botan (typically ``/usr/local``). You can override
+this by using the ``--prefix`` argument to
+``configure.py``, like so:
+
+``./configure.py --prefix=/opt <other arguments>``
+
+On some systems shared libraries might not be immediately visible to
+the runtime linker. For example, on Linux you may have to edit
+``/etc/ld.so.conf`` and run ``ldconfig`` (as root) in
+order for new shared libraries to be picked up by the linker. An
+alternative is to set your ``LD_LIBRARY_PATH`` shell variable
+to include the directory that the Botan libraries were installed into.
+
+On Mac OS X
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In general the Unix instructions above should apply, however OS X does
+not support ``LD_LIBRARY_PATH``. Thomas Keller suggests instead
+running ``install_name_tool`` between building and running the
+self-test program::
+
+  $ VERSION=1.10.0 # or whatever the current version is
+  $ install_name_tool -change $(otool -X -D libbotan-$VERSION.dylib) \
+       $PWD/libbotan-$VERSION.dylib check
+
+On MS Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you don't want to deal with building botan on Windows, check the
+website; commonly prebuilt Windows binaries with installers are
+available, especially for stable versions.
+
+You need to have a copy of Python installed, and have both Python and
+your chosen compiler in your path. Open a command shell (or the SDK
+shell), and run::
+
+   > python configure.py --cc=msvc (or --cc=gcc for MinGW) [--cpu=CPU]
+   > nmake
+   > nmake check # optional, but recommended
+   > nmake install
+
+For Win95 pre OSR2, the ``cryptoapi_rng`` module will not work,
+because CryptoAPI didn't exist. And all versions of NT4 lack the
+ToolHelp32 interface, which is how ``win32_stats`` does its slow
+polls, so a version of the library built with that module will not
+load under NT4. Later versions of Windows support both methods, so
+this shouldn't be much of an issue anymore.
+
+By default the install target will be ``C:\botan``; you can modify
+this with the ``--prefix`` option.
+
+When building your applications, all you have to do is tell the
+compiler to look for both include files and library files in
+``C:\botan``, and it will find both. Or you can move them to a
+place where they will be in the default compiler search paths (consult
+your documentation and/or local expert for details).
+
+Trickier Things
+----------------------------------------
+
+Modules Relying on Third Party Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are a fairly large number of modules included with Botan. Some
+of these are extremely useful, while others are only necessary in very
+unusual circumstances. Most are loaded (or not) automatically as
+necessary, but some require external libraries are thus must be
+enabled at build time; these include:
+
+ - ``--with-bzip2`` enables the filters providing bzip2 compression
+   and decompression. Requires the bzip2 development libraries to be
+   installed.
+
+ - ``--with-zlib`` enables the filters providing zlib compression
+   and decompression. Requires the zlib development libraries to be
+   installed.
+
+ - ``--with-gnump`` adds an alternative engine for public key cryptography
+   that uses the GNU MP library. GNU MP 4.1 or later is required.
+
+ - ``--with-openssl`` adds an engine that uses OpenSSL for some public
+   key operations and ciphers/hashes. OpenSSL 0.9.7 or later is
+   required. Note that (unlike GNU MP) OpenSSL's versions are not
+   always faster than the versions built into botan.
+
+.. _amalgamation:
+
+Amalgamation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also configure Botan to be built using only a single source
+file; this is quite convenient if you plan to embed the library into
+another application. To do so, run ``configure.py`` with
+whatever arguments you would ordinarily use, along with the option
+``--gen-amalgamation``. This will create two (rather large)
+files, ``botan_all.h`` and ``botan_all.cpp``.
+
+Whenever you would have included a botan header, you can then include
+``botan_all.h``, and include ``botan_all.cpp`` along
+with the rest of the source files in your build. If you want to be
+able to easily switch between amalgamated and non-amalgamated versions
+(for instance to take advantage of prepackaged versions of botan on
+operating systems that support it), you can instead ignore
+``botan_all.h`` and use the headers from
+``build/include`` as normal.
+
+Multiple Builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It may be useful to run multiple builds with different
+configurations. Specify ``--build-dir=<dir>`` to set up a build
+environment in a different directory.
+
+
+.. _configure_with_python3:
+
+Configuring the Build With Python 3.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The versions of Python begininning with 3 are (intentionally)
+incompatible with the (currently more common) 2.x series. If you want
+to use Python 3.1 to set up the build, you'll have to use the
+``2to3`` program (included in the Python distribution) on the
+script; this will convert the script to the Python 3.x dialect::
+
+  $ python ./configure.py
+  File "configure.py", line 860
+    except KeyError, e:
+                   ^
+  SyntaxError: invalid syntax
+  $ # incompatible python version, let's fix it
+  $ 2to3 -w configure.py
+  [...]
+  RefactoringTool: Files that were modified:
+  RefactoringTool: configure.py
+  $ python ./configure.py
+  [...]
+
+Local Configuration Settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You may want to do something peculiar with the configuration; to
+support this there is a flag to ``configure.py`` called
+``--with-local-config=<file>``. The contents of the file are
+inserted into ``build/build.h`` which is (indirectly) included
+into every Botan header and source file.
+
+Configuration Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are some configuration parameters which you may want to tweak
+before building the library. These can be found in ``config.h``. This
+file is overwritten every time the configure script is run (and does
+not exist until after you run the script for the first time).
+
+Also included in ``build/build.h`` are macros which let applications
+check which features are included in the current version of the
+library. All of them begin with ``BOTAN_HAS_``. For example, if
+``BOTAN_HAS_BLOWFISH`` is defined, then an application can include
+``<botan/blowfish.h>`` and use the Blowfish class.
+
+``BOTAN_MP_WORD_BITS``: This macro controls the size of the words used
+for calculations with the MPI implementation in Botan. You can choose
+8, 16, 32, or 64. Normally this defaults to either 32 or 64, depending
+on the processor. Unless you are building for a 8 or 16-bit CPU, this
+isn't worth messing with.
+
+``BOTAN_VECTOR_OVER_ALLOCATE``: The memory container ``SecureVector``
+will over-allocate requests by this amount (in elements). In several
+areas of the library, we grow a vector fairly often. By
+over-allocating by a small amount, we don't have to do allocations as
+often (which is good, because the allocators can be quite slow). If
+you *really* want to reduce memory usage, set it to 0. Otherwise, the
+default should be perfectly fine.
+
+``BOTAN_DEFAULT_BUFFER_SIZE``: This constant is used as the size of
+buffers throughout Botan. A good rule of thumb would be to use the
+page size of your machine. The default should be fine for most
+purposes.
+
+Building Applications
+----------------------------------------
+
+Unix
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Botan usually links in several different system libraries (such as
+``librt`` and ``libz``), depending on which modules are
+configured at compile time. In many environments, particularly ones
+using static libraries, an application has to link against the same
+libraries as Botan for the linking step to succeed. But how does it
+figure out what libraries it *is* linked against?
+
+The answer is to ask the ``botan-config`` script. This
+basically solves the same problem all the other ``*-config``
+scripts solve, and in basically the same manner.
+
+There are 4 options:
+
+``--prefix[=DIR]``: If no argument, print the prefix where Botan
+is installed (such as ``/opt`` or ``/usr/local``). If an
+argument is specified, other options given with the same command will
+execute as if Botan as actually installed at ``DIR`` and not
+where it really is; or at least where ``botan-config`` thinks
+it really is. I should mention that it
+
+``--version``: Print the Botan version number.
+
+``--cflags``: Print options that should be passed to the compiler
+whenever a C++ file is compiled. Typically this is used for setting
+include paths.
+
+``--libs``: Print options for which libraries to link to (this includes
+``-lbotan``).
+
+Your ``Makefile`` can run ``botan-config`` and get the
+options necessary for getting your application to compile and link,
+regardless of whatever crazy libraries Botan might be linked against.
+
+Botan also by default installs a file for ``pkg-config``,
+namespaced by the major and minor versions. So it can be used,
+for instance, as::
+
+  $ pkg-config botan-1.10 --modversion
+  1.10.0
+  $ pkg-config botan-1.10 --cflags
+  -I/usr/local/include
+  $ pkg-config botan-1.10 --libs
+  -L/usr/local/lib -lbotan -lm -lbz2 -lpthread -lrt
+
+MS Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+No special help exists for building applications on Windows. However,
+given that typically Windows software is distributed as binaries, this
+is less of a problem - only the developer needs to worry about it. As
+long as they can remember where they installed Botan, they just have
+to set the appropriate flags in their Makefile/project file.
+
+Language Wrappers
+----------------------------------------
+
+Building the Python wrappers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Python wrappers for Botan use Boost.Python, so you must have Boost
+installed. To build the wrappers, pass the flag
+``--with-boost-python`` to ``configure.py``. This will create a second
+makefile, ``Makefile.python``, with instructions for building the
+Python module. After building the library, execute::
+
+  $ make -f Makefile.python
+
+to build the module. Currently only Unix systems are supported, and
+the Makefile assumes that the version of Python you want to build
+against is the same one you used to run ``configure.py``.
+
+To install the module, use the ``install`` target.
+
+Examples of using the Python module can be seen in
+``doc/examples/python``
+
+Building the Perl XS wrappers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build the Perl XS wrappers, change your directory to
+``src/wrap/perl-xs`` and run ``perl Makefile.PL``, then run
+``make`` to build the module and ``make test`` to run the test
+suite::
+
+  $ perl Makefile.PL
+  Checking if your kit is complete...
+  Looks good
+  Writing Makefile for Botan
+  $ make
+  cp Botan.pm blib/lib/Botan.pm
+  AutoSplitting blib/lib/Botan.pm (blib/lib/auto/Botan)
+  /usr/bin/perl5.8.8 /usr/lib64/perl5/5.8.8/ExtUtils/xsubpp  [...]
+  g++ -c   -Wno-write-strings -fexceptions  -g   [...]
+  Running Mkbootstrap for Botan ()
+  chmod 644 Botan.bs
+  rm -f blib/arch/auto/Botan/Botan.so
+  g++  -shared Botan.o  -o blib/arch/auto/Botan/Botan.so  \
+             -lbotan -lbz2 -lpthread -lrt -lz     \
+
+  chmod 755 blib/arch/auto/Botan/Botan.so
+  cp Botan.bs blib/arch/auto/Botan/Botan.bs
+  chmod 644 blib/arch/auto/Botan/Botan.bs
+  Manifying blib/man3/Botan.3pm
+  $ make test
+  PERL_DL_NONLAZY=1 /usr/bin/perl5.8.8 [...]
+  t/base64......ok
+  t/filt........ok
+  t/hex.........ok
+  t/oid.........ok
+  t/pipe........ok
+  t/x509cert....ok
+  All tests successful.
+  Files=6, Tests=83,  0 wallclock secs ( 0.08 cusr +  0.02 csys =  0.10 CPU)
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 000000000..c3f8677fa
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,223 @@
+# -*- coding: utf-8 -*-
+#
+# botan documentation build configuration file, created by
+# sphinx-quickstart on Sun Apr  3 11:41:06 2011.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+sys.path.insert(0, os.pardir)
+
+import botan_version
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'botan'
+copyright = u'2000-2011, Jack Lloyd'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '%d.%d' % (botan_version.major, botan_version.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)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'botandoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# 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',
+   u'Jack Lloyd', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'botan', u'botan Documentation',
+     [u'Jack Lloyd'], 1)
+]
diff --git a/doc/credits.txt b/doc/credits.txt
index 636a99f99..076498756 100644
--- a/doc/credits.txt
+++ b/doc/credits.txt
@@ -1,78 +1,80 @@
-This is at least a partial credits-file of people that have
-contributed to the Botan project. It is sorted by name and formatted
-to allow easy grepping and beautification by scripts. The fields are:
-name (N), email (E), web-address (W), PGP key ID and fingerprint (P),
-description (D), and snail-mail address (S).
-
-Thanks,
-  Jack Lloyd
-----------
-
-N: Charles Brockman
-W: http://www.securitygenetics.com/
-D: documentation editing
-S: Oregon, USA
-
-N: Martin Doering
-E: [email protected]
-D: GF(p) arithmetic
-
-N: Olivier de Gaalon
-D: SQLite encryption codec (src/wrap/sqlite)
-
-N: Matthew Gregan
-D: Binary file I/O support, allocator fixes
-
-N: Hany Greiss
-D: Windows porting
-
-N: Manuel Hartl
-E: [email protected]
-W: http://www.flexsecure.de/
-D: ECDSA, ECDH
-
-N: Yves Jerschow
-E: [email protected]
-D: Optimizations for memory load/store and HMAC
-D: Support for IPv4 addresses in X.509 alternative names
-S: Germany
-
-N: Matt Johnston
-D: Allocator fixes and optimizations, decompressor fixes
-
-N: Peter J. Jones
-E: [email protected]
-D: Bzip2 compression module
-S: Colorado, USA
-
-N: Justin Karneges
-D: Qt support modules (mutexes and types), X.509 API design
-
-N: Jack Lloyd
-E: [email protected]
-W: http://www.randombit.net/
-P: 3F69 2E64 6D92 3BBE E7AE  9258 5C0F 96E8 4EC1 6D6B
-D: Original designer/author, maintainer 2001-current
-S: Vermont, USA
-
-N: Joel Low
-D: DLL symbol visibility and Windows DLL support in general
-
-N: Christoph Ludwig
-E: [email protected]
-D: GP(p) arithmetic
-
-N: Vaclav Ovsik
-E: [email protected]
-D: Perl XS module (src/wrap/perl-xs)
-
-N: Luca Piccarreta
-E: [email protected]
-D: x86/amd64 assembler, BigInt optimizations, Win32 mutex module
-S: Italy
-
-N: Falko Strenzke
-E: [email protected]
-W: http://www.flexsecure.de/
-D: GF(p) arithmetic, CVC, Shanks-Tonelli algorithm
-S: Darmstadt, Germany
+
+Credits
+========================================
+
+This is at least a partial credits-file of people that have contributed
+to botan. It is sorted by name and formatted to allow easy grepping
+and beautification by scripts. The fields are name (N), email (E),
+web-address (W), PGP key ID and fingerprint (P), description (D), and
+snail-mail address (S).
+
+::
+
+  N: Charles Brockman
+  W: http://www.securitygenetics.com/
+  D: documentation editing
+  S: Oregon, USA
+
+  N: Martin Doering
+  E: [email protected]
+  D: GF(p) arithmetic
+
+  N: Olivier de Gaalon
+  D: SQLite encryption codec (src/wrap/sqlite)
+
+  N: Matthew Gregan
+  D: Binary file I/O support, allocator fixes
+
+  N: Hany Greiss
+  D: Windows porting
+
+  N: Manuel Hartl
+  E: [email protected]
+  W: http://www.flexsecure.de/
+  D: ECDSA, ECDH
+
+  N: Yves Jerschow
+  E: [email protected]
+  D: Optimizations for memory load/store and HMAC
+  D: Support for IPv4 addresses in X.509 alternative names
+  S: Germany
+
+  N: Matt Johnston
+  D: Allocator fixes and optimizations, decompressor fixes
+
+  N: Peter J. Jones
+  E: [email protected]
+  D: Bzip2 compression module
+  S: Colorado, USA
+
+  N: Justin Karneges
+  D: Qt support modules (mutexes and types), X.509 API design
+
+  N: Jack Lloyd
+  E: [email protected]
+  W: http://www.randombit.net/
+  P: 3F69 2E64 6D92 3BBE E7AE  9258 5C0F 96E8 4EC1 6D6B
+  D: Original designer/author, maintainer 2001-current
+  S: Vermont, USA
+
+  N: Joel Low
+  D: DLL symbol visibility and Windows DLL support in general
+
+  N: Christoph Ludwig
+  E: [email protected]
+  D: GP(p) arithmetic
+
+  N: Vaclav Ovsik
+  E: [email protected]
+  D: Perl XS module (src/wrap/perl-xs)
+
+  N: Luca Piccarreta
+  E: [email protected]
+  D: x86/amd64 assembler, BigInt optimizations, Win32 mutex module
+  S: Italy
+
+  N: Falko Strenzke
+  E: [email protected]
+  W: http://www.flexsecure.de/
+  D: GF(p) arithmetic, CVC, Shanks-Tonelli algorithm
+  S: Darmstadt, Germany
diff --git a/doc/filters.txt b/doc/filters.txt
new file mode 100644
index 000000000..8ce396371
--- /dev/null
+++ b/doc/filters.txt
@@ -0,0 +1,782 @@
+
+Information Flow: Pipes and Filters
+========================================
+
+Many common uses of cryptography involve processing one or more
+streams of data. Botan provides services that make setting up data
+flows through various operations, such as compression, encryption, and
+base64 encoding. Each of these operations is implemented in what are
+called *filters* in Botan. A set of filters are created and placed into
+a *pipe*, and information "flows" through the pipe until it reaches
+the end, where the output is collected for retrieval. If you're
+familiar with the Unix shell environment, this design will sound quite
+familiar.
+
+Here is an example that uses a pipe to base64 encode some strings::
+
+  Pipe pipe(new Base64_Encoder); // pipe owns the pointer
+  pipe.start_msg();
+  pipe.write("message 1");
+  pipe.end_msg(); // flushes buffers, increments message number
+
+  // process_msg(x) is start_msg() && write(x) && end_msg()
+  pipe.process_msg("message2");
+
+  std::string m1 = pipe.read_all_as_string(0); // "message1"
+  std::string m2 = pipe.read_all_as_string(1); // "message2"
+
+Bytestreams in the pipe are grouped into messages; blocks of data that
+are processed in an identical fashion (ie, with the same sequence of
+filter operations). Messages are delimited by calls to ``start_msg``
+and ``end_msg``. Each message in a pipe has its own identifier, which
+currently is an integer that increments up from zero.
+
+The ``Base64_Encoder`` was allocated using ``new``; but where was it
+deallocated?  When a filter object is passed to a ``Pipe``, the pipe
+takes ownership of the object, and will deallocate it when it is no
+longer needed.
+
+There are two different ways to make use of messages. One is to send
+several messages through a ``Pipe`` without changing the ``Pipe``
+configuration, so you end up with a sequence of messages; one use of
+this would be to send a sequence of identically encrypted UDP packets,
+for example (note that the *data* need not be identical; it is just
+that each is encrypted, encoded, signed, etc in an identical
+fashion). Another is to change the filters that are used in the
+``Pipe`` between each message, by adding or removing filters;
+functions that let you do this are documented in the Pipe API section.
+
+Botan has about 40 filters that perform different operations on data.
+Here's code that uses one of them to encrypt a string with AES::
+
+  AutoSeeded_RNG rng,
+  SymmetricKey key(rng, 16); // a random 128-bit key
+  InitializationVector iv(rng, 16); // a random 128-bit IV
+
+  // The algorithm we want is specified by a string
+  Pipe pipe(get_cipher("AES-128/CBC", key, iv, ENCRYPTION));
+
+  pipe.process_msg("secrets");
+  pipe.process_msg("more secrets");
+
+  MemoryVector<byte> c1 = pipe.read_all(0);
+
+  byte c2[4096] = { 0 };
+  size_t got_out = pipe.read(c2, sizeof(c2), 1);
+  // use c2[0...got_out]
+
+Note the use of ``AutoSeeded_RNG``, which is a random number
+generator. If you want to, you can explicitly set up the random number
+generators and entropy sources you want to, however for 99% of cases
+``AutoSeeded_RNG`` is preferable.
+
+``Pipe`` also has convenience methods for dealing with
+``std::iostream``s. Here is an example of those, using the
+``Bzip_Compression`` filter (included as a module; if you have bzlib
+available, check the build instructions for how to enable it) to
+compress a file::
+
+  std::ifstream in("data.bin", std::ios::binary)
+  std::ofstream out("data.bin.bz2", std::ios::binary)
+
+  Pipe pipe(new Bzip_Compression);
+
+  pipe.start_msg();
+  in >> pipe;
+  pipe.end_msg();
+  out << pipe;
+
+However there is a hitch to the code above; the complete contents of
+the compressed data will be held in memory until the entire message
+has been compressed, at which time the statement ``out << pipe`` is
+executed, and the data is freed as it is read from the pipe and
+written to the file. But if the file is very large, we might not have
+enough physical memory (or even enough virtual memory!) for that to be
+practical. So instead of storing the compressed data in the pipe for
+reading it out later, we divert it directly to the file::
+
+  std::ifstream in("data.bin", std::ios::binary)
+  std::ofstream out("data.bin.bz2", std::ios::binary)
+
+  Pipe pipe(new Bzip_Compression, new DataSink_Stream(out));
+
+  pipe.start_msg();
+  in >> pipe;
+  pipe.end_msg();
+
+This is the first code we've seen so far that uses more than one
+filter in a pipe. The output of the compressor is sent to the
+``DataSink_Stream``. Anything written to a ``DataSink_Stream`` is
+written to a file; the filter produces no output. As soon as the
+compression algorithm finishes up a block of data, it will send it
+along, at which point it will immediately be written to disk; if you
+were to call ``pipe.read_all()`` after ``pipe.end_msg()``, you'd get
+an empty vector out.
+
+Here's an example using two computational filters::
+
+   AutoSeeded_RNG rng,
+   SymmetricKey key(rng, 32);
+   InitializationVector iv(rng, 16);
+
+   Pipe encryptor(get_cipher("AES/CBC/PKCS7", key, iv, ENCRYPTION),
+                  new Base64_Encoder);
+
+   encryptor.start_msg();
+   file >> encryptor;
+   encryptor.end_msg(); // flush buffers, complete computations
+   std::cout << encryptor;
+
+Fork
+---------------------------------
+
+It is common that you might receive some data and want to perform more
+than one operation on it (ie, encrypt it with Serpent and calculate
+the SHA-256 hash of the plaintext at the same time). That's where
+``Fork`` comes in. ``Fork`` is a filter that takes input and passes it
+on to *one or more* filters that are attached to it. ``Fork`` changes
+the nature of the pipe system completely: instead of being a linked
+list, it becomes a tree or acyclic graph.
+
+Each filter in the fork is given its own output buffer, and thus its
+own message. For example, if you had previously written two messages
+into a pipe, then you start a new one with a fork that has three
+paths of filter's inside it, you add three new messages to the
+pipe. The data you put into the pipe is duplicated and sent
+into each set of filter and the eventual output is placed into a
+dedicated message slot in the pipe.
+
+Messages in the pipe are allocated in a depth-first manner. This is only
+interesting if you are using more than one fork in a single pipe.
+As an example, consider the following::
+
+   Pipe pipe(new Fork(
+                new Fork(
+                   new Base64_Encoder,
+                   new Fork(
+                      NULL,
+                      new Base64_Encoder
+                      )
+                   ),
+                new Hex_Encoder
+                )
+      );
+
+In this case, message 0 will be the output of the first
+``Base64_Encoder``, message 1 will be a copy of the input (see below
+for how fork interprets NULL pointers), message 2 will be the output
+of the second ``Base64_Encoder``, and message 3 will be the output of
+the ``Hex_Encoder``. This results in message numbers being allocated
+in a top to bottom fashion, when looked at on the screen. However,
+note that there could be potential for bugs if this is not
+anticipated. For example, if your code is passed a filter, and you
+assume it is a "normal" one that only uses one message, your message
+offsets would be wrong, leading to some confusion during output.
+
+If Fork's first argument is a null pointer, but a later argument is
+not, then Fork will feed a copy of its input directly through. Here's
+a case where that is useful::
+
+   // have std::string ciphertext, auth_code, key, iv, mac_key;
+
+   Pipe pipe(new Base64_Decoder,
+             get_cipher(``AES-128'', key, iv, DECRYPTION),
+             new Fork(
+                0
+                new MAC_Filter(``HMAC(SHA-1)'', mac_key)
+             )
+      );
+
+   pipe.process_msg(ciphertext);
+   std::string plaintext = pipe.read_all_as_string(0);
+   SecureVector<byte> mac = pipe.read_all(1);
+
+   if(mac != auth_code)
+      error();
+
+Here we wanted to not only decrypt the message, but send the decrypted
+text through an additional computation, in order to compute the
+authentication code.
+
+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")),
+            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.
+
+Chain
+---------------------------------
+
+A ``Chain`` filter creates a chain of filters and encapsulates them
+inside a single filter (itself). This allows a sequence of filters to
+become a single filter, to be passed into or out of a function, or to
+a ``Fork`` constructor.
+
+You can call ``Chain``'s constructor with up to four ``Filter``
+pointers (they will be added in order), or with an array of filter
+pointers and a ``size_t`` that tells ``Chain`` how many filters are in
+the array (again, they will be attached in order). Here's the example
+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")
+                )
+           );
+
+Sources and Sinks
+----------------------------------------
+
+Data Sources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``DataSource`` is a simple abstraction for a thing that stores bytes. This
+type is used heavily in the areas of the API related to ASN.1
+encoding/decoding. The following types are ``DataSource``s: ``Pipe``,
+``SecureQueue``, and a couple of special purpose ones:
+``DataSource_Memory`` and ``DataSource_Stream``.
+
+You can create a ``DataSource_Memory`` with an array of bytes and a length
+field. The object will make a copy of the data, so you don't have to worry
+about keeping that memory allocated. This is mostly for internal use, but if it
+comes in handy, feel free to use it.
+
+A ``DataSource_Stream`` is probably more useful than the memory based
+one. Its constructors take either a ``std::istream`` or a
+``std::string``. If it's a stream, the data source will use the
+``istream`` to satisfy read requests (this is particularly useful to use
+with ``std::cin``). If the string version is used, it will attempt to open
+up a file with that name and read from it.
+
+Data Sinks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``DataSink`` (in ``data_snk.h``) is a ``Filter`` that
+takes arbitrary amounts of input, and produces no output. This means
+it's doing something with the data outside the realm of what
+``Filter``/``Pipe`` can handle, for example, writing it to a
+file (which is what the ``DataSink_Stream`` does). There is no
+need for ``DataSink``s that write to a ``std::string`` or memory
+buffer, because ``Pipe`` can handle that by itself.
+
+Here's a quick example of using a ``DataSink``, which encrypts
+``in.txt`` and sends the output to ``out.txt``. There is
+no explicit output operation; the writing of ``out.txt`` is
+implicit::
+
+   DataSource_Stream in("in.txt");
+   Pipe pipe(new CBC_Encryption("AES-128", "PKCS7", key, iv),
+             new DataSink_Stream("out.txt"));
+   pipe.process_msg(in);
+
+A real advantage of this is that even if "in.txt" is large, only as
+much memory is needed for internal I/O buffers will be used.
+
+The Pipe API
+---------------------------------
+
+Initializing Pipe
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, ``Pipe`` will do nothing at all; any input placed into the
+``Pipe`` will be read back unchanged. Obviously, this has limited
+utility, and presumably you want to use one or more filters to somehow
+process the data. First, you can choose a set of filters to initialize
+the ``Pipe`` via the constructor. You can pass it either a set of up
+to four filter pointers, or a pre-defined array and a length::
+
+   Pipe pipe1(new Filter1(/*args*/), new Filter2(/*args*/),
+              new Filter3(/*args*/), new Filter4(/*args*/));
+   Pipe pipe2(new Filter1(/*args*/), new Filter2(/*args*/));
+
+   Filter* filters[5] = {
+     new Filter1(/*args*/), new Filter2(/*args*/), new Filter3(/*args*/),
+     new Filter4(/*args*/), new Filter5(/*args*/) /* more if desired... */
+   };
+   Pipe pipe3(filters, 5);
+
+This is by far the most common way to initialize a ``Pipe``. However,
+occasionally a more flexible initialization strategy is necessary;
+this is supported by 4 member functions. These functions may only be
+used while the pipe in question is not in use; that is, either before
+calling ``start_msg``, or after ``end_msg`` has been called (and no
+new calls to ``start_msg`` have been made yet).
+
+.. cpp:function:: void Pipe::prepend(Filter* filter)
+
+  Calling ``prepend`` will put the passed filter first in the list of
+  transformations. For example, if you prepend a filter implementing
+  encryption, and the pipe already had a filter that hex encoded the
+  input, then the next message processed would be first encrypted,
+  and *then* hex encoded.
+
+.. cpp:function:: void Pipe::append(Filter* filter)
+
+  Like ``prepend``, but places the filter at the end of the message
+  flow. This doesn't always do what you expect if there is a fork.
+
+.. cpp:function:: void Pipe::pop()
+
+  Removes the first filter in the flow.
+
+.. cpp:function:: void Pipe::reset()
+
+  Removes all the filters that the pipe currently holds - it is reset
+  to an empty/no-op state.  Any data that is being retained by the
+  pipe is retained after a ``reset``, and ``reset`` does not affect
+  message numbers (discussed later).
+
+Giving Data to a Pipe
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Input to a ``Pipe`` is delimited into messages, which can be read from
+independently (ie, you can read 5 bytes from one message, and then all of
+another message, without either read affecting any other messages).
+
+.. cpp:function:: void Pipe::start_msg()
+
+  Starts a new message; if a message was already running, an exception is
+  thrown. After this function returns, you can call ``write``.
+
+.. cpp:function:: void Pipe::write(const byte* input, size_t length)
+
+.. cpp:function:: void Pipe::write(const MemoryRegion<byte>& input)
+
+.. cpp:function:: void Pipe::write(const std::string& input)
+
+.. cpp:function:: void Pipe::write(DataSource& input)
+
+.. cpp:function:: void Pipe::write(byte input)
+
+  All versions of ``write`` write the input into the filter sequence.
+  If a message is not currently active, an exception is thrown.
+
+.. cpp:function:: void Pipe::end_msg()
+
+  End the currently active message
+
+Sometimes, you may want to do only a single write per message. In this
+case, you can use the ``process_msg`` series of functions, which start
+a message, write their argument into the pipe, and then end the
+message. In this case you would not make any explicit calls to
+``start_msg``/``end_msg``.
+
+Pipes can also be used with the ``>>`` operator, and will accept a
+``std::istream``, or on Unix systems with the ``fd_unix`` module, a
+Unix file descriptor. In either case, the entire contents of the file
+will be read into the pipe.
+
+Getting Output from a Pipe
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieving the processed data from a pipe is a bit more complicated,
+for various reasons. The pipe will separate each message into a
+separate buffer, and you have to retrieve data from each message
+independently. Each of the reader functions has a final parameter that
+specifies what message to read from. If this parameter is set to
+``Pipe::DEFAULT_MESSAGE``, it will read the current default message
+(``DEFAULT_MESSAGE`` is also the default value of this parameter).
+
+Functions in ``Pipe`` related to reading include:
+
+.. cpp:function:: size_t Pipe::read(byte* out, size_t len)
+
+  Reads up to ``len`` bytes into ``out``, and returns the number of
+  bytes actually read.
+
+.. cpp:function:: size_t Pipe::peek(byte* out, size_t len)
+
+  Acts exactly like `read`, except the data is not actually read; the
+  next read will return the same data.
+
+.. cpp:function:: SecureVector<byte> Pipe::read_all()
+
+  Reads the entire message into a buffer and returns it
+
+.. cpp:function:: std::string Pipe::read_all_as_string()
+
+  Like ``read_all``, but it returns the data as a ``std::string``.
+  No encoding is done; if the message contains raw binary, so will
+  the string.
+
+.. cpp:function:: size_t Pipe::remaining()
+
+  Returns how many bytes are left in the message
+
+.. cpp:function:: Pipe::message_id default_msg()
+
+  Returns the current default message number
+
+.. cpp:function:: Pipe::message_id Pipe::message_count()
+
+  Returns the total number of messages currently in the pipe
+
+.. cpp:function:: Pipe::set_default_msg(Pipe::message_id msgno)
+
+  Sets the default message number (which must be a valid message
+  number for that pipe). The ability to set the default message number
+  is particularly important in the case of using the file output
+  operations (``<<`` with a ``std::ostream`` or Unix file descriptor),
+  because there is no way to specify the message explicitly when using
+  the output operator.
+
+Pipe I/O for Unix File Descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is a minor feature, but it comes in handy sometimes. In all
+installations of the library, Botan's ``Pipe`` object overloads the
+``<<`` and ``>>`` operators for C++ iostream objects,
+which is usually more than sufficient for doing I/O.
+
+However, there are cases where the iostream hierarchy does not map well to
+local 'file types', so there is also the ability to do I/O directly with Unix
+file descriptors. This is most useful when you want to read from or write to
+something like a TCP or Unix-domain socket, or a pipe, since for simple file
+access it's usually easier to just use C++'s file streams.
+
+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
+---------------------------------
+
+This section documents most of the useful filters included in the
+library.
+
+Keyed Filters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A few sections ago, it was mentioned that ``Pipe`` can process
+multiple messages, treating each of them the same. Well, that was a
+bit of a lie. There are some algorithms (in particular, block ciphers
+not in ECB mode, and all stream ciphers) that change their state as
+data is put through them.
+
+Naturally, you might well want to reset the keys or (in the case of
+block cipher modes) IVs used by such filters, so multiple messages can
+be processed using completely different keys, or new IVs, or new keys
+and IVs, or whatever.  And in fact, even for a MAC or an ECB block
+cipher, you might well want to change the key used from message to
+message.
+
+Enter ``Keyed_Filter``, which acts as an abstract interface for any
+filter that is uses keys: block cipher modes, stream ciphers, MACs,
+and so on. It has two functions, ``set_key`` and ``set_iv``. Calling
+``set_key`` will set (or reset) the key used by the algorithm. Setting
+the IV only makes sense in certain algorithms -- a call to ``set_iv``
+on an object that doesn't support IVs will cause an exception. You
+must call ``set_key`` *before* calling ``set_iv``.
+
+Here's a example::
+
+   Keyed_Filter *cast, *hmac;
+   Pipe pipe(new Base64_Decoder,
+             // Note the assignments to the cast and hmac variables
+             cast = new CBC_Decryption("CAST-128", "PKCS7", cast_key, iv),
+             new Fork(
+                0, // Read the section 'Fork' to understand this
+                new Chain(
+                   hmac = new MAC_Filter("HMAC(SHA-1)", mac_key, 12),
+                   new Base64_Encoder
+                   )
+                )
+      );
+   pipe.start_msg();
+   // use pipe for a while, decrypt some stuff, derive new keys and IVs
+   pipe.end_msg();
+
+   cast->set_key(cast_key2);
+   cast->set_iv(iv2);
+   hmac->set_key(mac_key2);
+
+   pipe.start_msg();
+   // use pipe for some other things
+   pipe.end_msg();
+
+There are some requirements to using ``Keyed_Filter`` that you must
+follow. If you call ``set_key`` or ``set_iv`` on a filter that
+is owned by a ``Pipe``, you must do so while the ``Pipe`` is
+"unlocked". This refers to the times when no messages are being processed by
+``Pipe`` -- either before ``Pipe``'s ``start_msg`` is called, or
+after ``end_msg`` is called (and no new call to ``start_msg``
+has happened yet). Doing otherwise will result in undefined behavior, probably
+silently getting invalid output.
+
+And remember: if you're resetting both values, reset the key *first*.
+
+Cipher Filters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Getting a hold of a ``Filter`` implementing a cipher is very
+easy. Make sure you're including the header ``lookup.h``, and
+then call ``get_cipher``. You will pass the return value
+directly into a ``Pipe``. There are a couple different functions
+which do varying levels of initialization:
+
+.. cpp:function:: Keyed_Filter* get_cipher(std::string cipher_spec, SymmetricKey key, InitializationVector iv, Cipher_Dir dir)
+
+.. cpp:function:: Keyed_Filter* get_cipher(std::string cipher_spec, SymmetricKey key, Cipher_Dir dir)
+
+The version that doesn't take an IV is useful for things that don't
+use them, like block ciphers in ECB mode, or most stream ciphers. If
+you specify a cipher spec that does want a IV, and you use the version
+that doesn't take one, an exception will be thrown. The ``dir``
+argument can be either ``ENCRYPTION`` or ``DECRYPTION``.
+
+The cipher_spec is a string that specifies what cipher is to be
+used. The general syntax for "cipher_spec" is "STREAM_CIPHER",
+"BLOCK_CIPHER/MODE", or "BLOCK_CIPHER/MODE/PADDING". In the case of
+stream ciphers, no mode is necessary, so just the name is
+sufficient. A block cipher requires a mode of some sort, which can be
+"ECB", "CBC", "CFB(n)", "OFB", "CTR-BE", or "EAX(n)". The argument to
+CFB mode is how many bits of feedback should be used. If you just use
+"CFB" with no argument, it will default to using a feedback equal to
+the block size of the cipher. EAX mode also takes an optional bit
+argument, which tells EAX how large a tag size to use~--~generally
+this is the size of the block size of the cipher, which is the default
+if you don't specify any argument.
+
+In the case of the ECB and CBC modes, a padding method can also be
+specified. If it is not supplied, ECB defaults to not padding, and CBC
+defaults to using PKCS #5/#7 compatible padding. The padding methods
+currently available are "NoPadding", "PKCS7", "OneAndZeros", and
+"CTS". CTS padding is currently only available for CBC mode, but the
+others can also be used in ECB mode.
+
+Some example "cipher_spec arguments are: "AES-128/CBC",
+"Blowfish/CTR-BE", "Serpent/XTS", and "AES-256/EAX".
+
+"CTR-BE" refers to counter mode where the counter is incremented as if
+it were a big-endian encoded integer. This is compatible with most
+other implementations, but it is possible some will use the
+incompatible little endian convention. This version would be denoted
+as "CTR-LE" if it were supported.
+
+"EAX" is a new cipher mode designed by Wagner, Rogaway, and
+Bellare. It is an authenticated cipher mode (that is, no separate
+authentication is needed), has provable security, and is free from
+patent entanglements. It runs about half as fast as most of the other
+cipher modes (like CBC, OFB, or CTR), which is not bad considering you
+don't need to use an authentication code.
+
+Hashes and MACs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Hash functions and MACs don't need anything special when it comes to
+filters. Both just take their input and produce no output until
+``end_msg`` is called, at which time they complete the hash or MAC and
+send that as output.
+
+These filters take a string naming the type to be used. If for some
+reason you name something that doesn't exist, an exception will be thrown.
+
+.. cpp:function:: Hash_Filter::Hash_Filter(std::string hash, size_t outlen = 0)
+
+  This constructor creates a filter that hashes its input with
+  ``hash``. When ``end_msg`` is called on the owning pipe, the hash is
+  completed and the digest is sent on to the next filter in the
+  pipeline. The parameter ``outlen`` specifies how many bytes of the
+  hash output will be passed along to the next filter when ``end_msg``
+  is called. By default, it will pass the entire hash.
+
+  Examples of names for ``Hash_Filter`` are "SHA-1" and "Whirlpool".
+
+.. cpp:function:: MAC_Filter::MAC_Filter(std::string mac, SymmetricKey key, size_t outlen = 0)
+
+  This constructor takes a name for a mac, such as "HMAC(SHA-1)" or
+  "CMAC(AES-128)", along with a key to use. The optional ``outlen``
+  works the same as in ``Hash_Filter``.
+
+PK Filters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are four classes in this category, ``PK_Encryptor_Filter``,
+``PK_Decryptor_Filter``, ``PK_Signer_Filter``, and
+``PK_Verifier_Filter``. Each takes a pointer to an object of the
+appropriate type (``PK_Encryptor``, ``PK_Decryptor``, etc) that is
+deleted by the destructor. These classes are found in ``pk_filts.h``.
+
+Three of these, for encryption, decryption, and signing are much the
+same in terms of dataflow - ach of them buffers its input until the
+end of the message is marked with a call to the ``end_msg``
+function. Then they encrypt, decrypt, or sign the entire input as a
+single blob and send the output (the ciphertext, the plaintext, or the
+signature) into the next filter.
+
+Signature verification works a little differently, because it needs to
+know what the signature is in order to check it. You can either pass
+this in along with the constructor, or call the function
+``set_signature`` -- with this second method, you need to keep
+a pointer to the filter around so you can send it this command. In
+either case, after ``end_msg`` is called, it will try to
+verify the signature (if the signature has not been set by either
+method, an exception will be thrown here). It will then send a single
+byte onto the next filter -- a 1 or a 0, which specifies whether the
+signature verified or not (respectively).
+
+For more information about PK algorithms (including creating the
+appropriate objects to pass to the constructors), see
+:ref:`public_key_crypto`.
+
+Encoders
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Often you want your data to be in some form of text (for sending over
+channels that aren't 8-bit clean, printing it, etc). The filters
+``Hex_Encoder`` and ``Base64_Encoder`` will convert arbitrary binary
+data into hex or base64 formats. Not surprisingly, you can use
+``Hex_Decoder`` and ``Base64_Decoder`` to convert it back into its
+original form.
+
+Both of the encoders can take a few options about how the data should
+be formatted (all of which have defaults). The first is a ``bool``
+which says if the encoder should insert line breaks. This defaults to
+false. Line breaks don't matter either way to the decoder, but it
+makes the output a bit more appealing to the human eye, and a few
+transport mechanisms (notably some email systems) limit the maximum
+line length.
+
+The second encoder option is an integer specifying how long such lines
+will be (obviously this will be ignored if line-breaking isn't being
+used). The default tends to be in the range of 60-80 characters, but
+is not specified. If you want a specific value, set it. Otherwise the
+default should be fine.
+
+Lastly, ``Hex_Encoder`` takes an argument of type ``Case``, which can
+be ``Uppercase`` or ``Lowercase`` (default is ``Uppercase``). This
+specifies what case the characters A-F should be output as. The base64
+encoder has no such option, because it uses both upper and lower case
+letters for its output.
+
+You can find the declarations for these types in ``hex_filt.h`` and
+``b64_filt.h``.
+
+Compressors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two compression algorithms supported by Botan, zlib and
+bzip2. Only lossless compression algorithms are currently supported by
+Botan, because they tend to be the most useful for
+cryptography. However, it is very reasonable to consider supporting
+something like GSM speech encoding (which is lossy), for use in
+encrypted voice applications.
+
+You should always compress *before* you encrypt, because encryption seeks
+to hide the redundancy that compression is supposed to try to find and remove.
+
+To test for Bzip2, check to see if ``BOTAN_HAS_COMPRESSOR_BZIP2`` is
+defined. If so, you can include ``botan/bzip2.h``, which will declare
+a pair of ``Filter`` objects: ``Bzip2_Compression`` and
+``Bzip2_Decompression``.
+
+You should be prepared to take an exception when using the
+decompressing filter, for if the input is not valid bzip2 data, that
+is what you will receive. You can specify the desired level of
+compression to ``Bzip2_Compression``'s constructor as an integer
+between 1 and 9, 1 meaning worst compression, and 9 meaning the
+best. The default is to use 9, since small values take the same amount
+of time, just use a little less memory.
+
+Zlib compression works much like Bzip2 compression. The only
+differences in this case are that the macro is
+``BOTAN_HAS_COMPRESSOR_ZLIB``, the header you need to include is
+called ``botan/zlib.h`` (remember that you shouldn't just ``#include
+<zlib.h>``, or you'll get the regular zlib API, which is not what you
+want). The Botan classes for zlib compression/decompression are called
+``Zlib_Compression`` and ``Zlib_Decompression``.
+
+Like Bzip2, a ``Zlib_Decompression`` object will throw an exception if
+invalid (in the sense of not being in the Zlib format) data is passed
+into it.
+
+While the zlib compression library uses the same compression algorithm
+as the gzip and zip programs, the format is different. The zlib format
+is defined in RFC 1950.
+
+Writing New Filters
+---------------------------------
+
+The system of filters and pipes was designed in an attempt to make it
+as simple as possible to write new filter types. There are four
+functions that need to be implemented by a class deriving from
+``Filter``:
+
+.. cpp:function:: void Filter::write(const byte* input, size_t length)
+
+  This function is what is called when a filter receives input for it
+  to process. The filter is not required to process the data right
+  away; many filters buffer their input before producing any output. A
+  filter will usually have ``write`` called many times during its
+  lifetime.
+
+.. cpp:function:: void Filter::send(byte* output, size_t length)
+
+  Eventually, a filter will want to produce some output to send along
+  to the next filter in the pipeline. It does so by calling ``send``
+  with whatever it wants to send along to the next filter. There is
+  also a version of ``send`` taking a single byte argument, as a
+  convenience.
+
+.. cpp:function:: void Filter::start_msg()
+
+  Implementing this function is optional. Implement it if your filter
+  would like to do some processing or setup at the start of each
+  message, such as allocating a data structure.
+
+.. cpp:function:: void Filter::end_msg()
+
+  Implementing this function is optional. It is called when it has
+  been requested that filters finish up their computations. The filter
+  should finish up with whatever computation it is working on (for
+  example, a compressing filter would flush the compressor and
+  ``send`` the final block), and empty any buffers in preparation for
+  processing a fresh new set of input.
+
+Additionally, if necessary, filters can define a constructor that
+takes any needed arguments, and a destructor to deal with deallocating
+memory, closing files, etc.
+
diff --git a/doc/fips140.tex b/doc/fips140.tex
deleted file mode 100644
index 8b2004508..000000000
--- a/doc/fips140.tex
+++ /dev/null
@@ -1,156 +0,0 @@
-\documentclass{article}
-
-\setlength{\textwidth}{6.5in}
-\setlength{\textheight}{9in}
-
-\setlength{\headheight}{0in}
-\setlength{\topmargin}{0in}
-\setlength{\headsep}{0in}
-
-\setlength{\oddsidemargin}{0in}
-\setlength{\evensidemargin}{0in}
-
-\title{\textbf{Botan FIPS 140-2 Security Policy}}
-\author{Jack Lloyd \\
-        \texttt{[email protected]}}
-\date{}
-
-\newcommand{\filename}[1]{\texttt{#1}}
-\newcommand{\module}[1]{\texttt{#1}}
-
-\newcommand{\type}[1]{\texttt{#1}}
-\newcommand{\function}[1]{\textbf{#1}}
-\newcommand{\macro}[1]{\texttt{#1}}
-
-\begin{document}
-
-\maketitle
-
-\tableofcontents
-
-\parskip=5pt
-%\baselineskip=15pt
-
-\pagebreak
-
-\section{Introduction}
-
-\emph{Note that this is a draft, and almost certainly does not comply with what
-FIPS 140-2 wants (also it's incomplete). In any case, there is no way for me to
-afford paying the validation lab, so this is all theoretical.}
-
-\emph{I would welcome comments from people who are familiar with the FIPS 140
-process. I am currently basing this off a few dozen other security policies and
-the FIPS itself.}
-
-\subsection{Purpose}
-
-This document is a security policy for the Botan C++ crypto library for use in
-a FIPS 140-2 Level 1 validation process. It describes how to configure and use
-the library to comply with the requirements of FIPS 140-2.
-
-This document is non-proprietary, and may be freely reproduced and distributed
-in unmodified form.
-
-\subsection{Product Description}
-
-The Botan C++ crypto library (hereafter ``Botan'' or ``the library'') is an
-open source C++ class library providing a general-purpose interface to a wide
-variety of cryptographic algorithms and formats (such as X.509v3 and PKCS
-\#10). It runs on most Win32 and POSIX-like systems, including Windows
-NT/2000/XP, MacOS X, Linux, Solaris, FreeBSD, and QNX. However, only versions
-running on \emph{(goal:)} Windows XP, Linux, and Solaris have been validated by
-FIPS 140-2 at this time.
-
-\subsection{Algorithms}
-
-The library contains the following FIPS Approved algorithms: RSA, DSA, DES,
-TripleDES, Skipjack, AES, SHA-1, HMAC, the X9.19 DES MAC, and the FIPS 186-2
-SHA-1 RNG. Other (non-Approved) algorithms, such as MD5 and Diffie-Hellman, are
-also included.
-
-\section{Initialization}
-
-Certain tests are only performed if the flag ``fips140'' is passed as part of
-the initialization process to the library (the argument to
-\type{LibraryInitializer} or \function{Init::initialize}). Known answer tests
-and key generation self-checks for RSA and DSA are always performed, regardless
-of this setting. This flag must be passed by any application which desires
-using the FIPS 140 mode of operation.
-
-\section{Roles and Services}
-
-Botan supports two roles, the User and the Crypto Officer. Authentication is
-not performed by the module; all authentication is implicitly done by the
-operating system.
-
-\subsection{User Role}
-
-The user has the ability to access the services of the module. This role is
-implicitly selected whenever the module's services are accessed.
-
-\subsection{Crypto Officer Role}
-
-The crypto officer has all of the powers of the user, and in addition has the
-power to install and uninstall the module and to configure the operating
-system. This role is implicitly selected whenever these actions are performed.
-
-\section{Key Management}
-
-\subsection{Key Import/Export}
-
-Symmetric keys can be imported and exported in either unencrypted, encrypted,
-or split-knowledge forms, as the application desires. Private keys for
-asymmetric algorithms can be imported and exported as either encrypted or
-unencrypted PKCS \#8 structures. The library natively supports PKCS \#5
-encryption with TripleDES for encrypting private keys.
-
-\subsection{Key Storage}
-
-In no case does the library itself import or export keys from/to an external
-storage device; all such operations are done explicitly by the application. It
-is the responsibly of the operator to ensure than any such operations comply
-with the requirements of FIPS 140-2 Level 1.
-
-\subsection{Key Generation}
-
-Keys for symmetric algorithms (such as DES, AES, and HMAC) are generated by an
-Approved RNG, by generating a random byte string of the appropriate size, and
-using it as a key.
-
-DSA keys are generated as specified in FIPS 186-2 (or not?). RSA keys are
-generated as specified in ANSI X9.31 (\emph{I think...}). Diffie-Hellman keys
-are generated in a manner compatible with ANSI X9.42. All newly created DSA and
-RSA keys are checked with a pairwise consistency test before being returned to
-the caller. A pairwise consistency check can be performed on any RSA, DSA, or
-Diffie-Hellman key by calling the \function{check\_key} member function with
-an argument of \type{true}.
-
-\subsection{Key Establishment}
-
-Botan supports using RSA or Diffie-Hellman to establish keys. RSA can be used
-with PKCS \#1 v1.5 or OAEP padding. None of these methods are FIPS Approved,
-but Annex D of FIPS 140-2 allows for their use until such time as a FIPS
-Approved asymmetric key establishment method is established.
-
-\subsection{Key Protection / Zeroization}
-
-Keys are protected against external access by the operating system's memory and
-process protection mechanisms. If the library is used by multiple processes at
-once, the OS virtual memory mechanisms ensure that each version will have it's
-own data space (and thus, keys are not shared among multiple processes).
-
-All keys and other sensitive materials are zeroed in memory before being
-released to the system.
-
-On Windows systems the \function{VirtualLock} system call is used to notify the
-operating system that the memory containing potentially sensitive keying
-material is not swapped to disk, preventing an attacker from applying disk
-forenistics techniques to recovery data.
-
-On Unix systems, Botan allocates memory from file-backed memory mappings, which
-are thoroughly erased when the memory is freed.
-
-\section{References}
-
-\end{document}
diff --git a/doc/indent.el b/doc/indent.el
index 9811bf848..7fa2540b0 100644
--- a/doc/indent.el
+++ b/doc/indent.el
@@ -2,19 +2,14 @@
 ; get everything perfectly correct, but it's pretty close. Copy this code into
 ; your .emacs file, or use M-x eval-buffer. Make sure to also set
 ; indent-tabs-mode to nil so spaces are inserted instead.
-
+;
 ; This style is basically Whitesmiths style with 3 space indents (the Emacs
 ; "whitesmith" style seems more like a weird Whitesmiths/Allman mutant style).
-
+;
 ; To activate using this style, open the file you want to edit and run this:
-; M-x c-set-style <RET> and then enter "botan". Alternately, put something
-; like this in your .emacs file to make it the default style:
+; M-x c-set-style <RET> and then enter "botan".
 
-; (add-hook 'c++-mode-common-hook
-;   (function (lambda()
-;     (c-add-style "botan" botan t))))
-
-(setq botan '(
+(setq botan-style '(
    (c-basic-offset . 3)
    (c-comment-only-line-offset . 0)
    (c-offsets-alist
@@ -55,3 +50,6 @@
       (label . 0)
       )
 ))
+
+(add-hook 'c++-mode-common-hook
+  (function (lambda () (c-add-style "botan" botan-style nil))))
diff --git a/doc/index.txt b/doc/index.txt
new file mode 100644
index 000000000..1dfa6abcc
--- /dev/null
+++ b/doc/index.txt
@@ -0,0 +1,27 @@
+
+Botan Reference Manual
+=================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   building
+   filters
+   pubkey
+   x509
+   lowlevel
+   bigint
+   algos
+   pgpkeys
+   license
+   credits
+   log
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/doc/internals.tex b/doc/internals.tex
deleted file mode 100644
index 5b1650f6e..000000000
--- a/doc/internals.tex
+++ /dev/null
@@ -1,179 +0,0 @@
-\documentclass{article}
-
-\setlength{\textwidth}{6.75in} % 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{Botan Internals}
-\author{Jack Lloyd ([email protected])}
-\date{August 20, 2006}
-
-\newcommand{\filename}[1]{\texttt{#1}}
-\newcommand{\manpage}[2]{\texttt{#1}(#2)}
-
-\newcommand{\function}[1]{\textbf{#1}}
-\newcommand{\type}[1]{\texttt{#1}}
-\renewcommand{\arg}[1]{\textsl{#1}}
-
-\begin{document}
-
-\maketitle
-
-\tableofcontents
-
-\parskip=5pt
-
-\section{Introduction}
-
-This document is intended to document some of the trickier and/or more
-complicated parts of Botan. This is not going to be terribly useful if
-you just want to use the library, but for people wishing to understand
-how it works, or contribute new code to it, it will hopefully prove
-helpful.
-
-I've realized that a lot of things Botan does internally are pretty
-hard to understand, and that a lot of things are only inside my head,
-which is a bad place for them to be (things tend to get lost in there,
-not to mention the possibility that I'll get hit by a truck next
-week).
-
-This document is currently very incomplete. I'll be working on it as I
-have time.
-
-\pagebreak
-
-\section{Filter}
-
-\type{Filter} is one of the core abstractions of the library. It is
-used to represent any sort of transformation. Nearly all
-\type{Filter}s are linear; they take input from a single source and
-send their output (if any) to another single \type{Filter}. The one
-exception is \type{Fanout\_Filter}, which uses friend access to
-\type{Filter} in order to allow for multiple \type{Filter}s to attach
-to its output. This special access is used by the Chain and Fork
-filters; Chain encapsulates one or more \type{Filter}s into a single
-Filter, and Fork sends its input to a set of several \type{Filter}
-objects.
-
-The majority of the relations between filters is maintained by the
-\type{Pipe} object which ``owns'' the \type{Filter}s.
-
-\section{Pipe}
-
-\type{Pipe} is, conceptually, a tree structure of \type{Filter}
-objects. There is a single unique top, and an arbitrary number of
-leaves (which are \type{SecureQueue} objects). \type{SecureQueue} is a
-simple \type{Filter} that buffers its input.
-
-Writing into the pipe writes into the top of the tree. The filter at
-the top of the tree writes its output into the next \type{Filter}, and
-so on until eventually data trickles down into the bottommost
-\type{Filter}s, where the data is stored for later retrieval.
-
-When a new message is started, \type{Pipe} searches through the tree
-of \type{Filter}s and finds places where the \arg{next} field of the
-\type{Filter} is NULL. This implies that it was the lowest layer of
-the \type{Filter} tree that the user added. It then adds
-\type{SecureQueue} objects onto these \type{Filter}s. These queues are
-also stored in an deque; this is so \type{Pipe} can read from them
-later without doing a tree traversal each time.
-
-\type{Pipe} will, if asked, destroy the existing tree structure, in
-order to create a new one. However, the queue objects are not deleted,
-because \type{Pipe} might be asked to read from them later (while
-\type{Pipe} could delete all the messages in this case, the principle
-of least astonishment suggested keeping them).
-
-What I wrote about \type{Pipe} keeing the queues in a deque is a
-lie. Sort of. It keeps them in an object called
-\type{Output\_Buffers}, which keeps them in a
-deque. \type{Output\_Buffers} is intended to abstract away how message
-queues are stored from \type{Pipe}. After a queue has been added to
-the output buffers object, \type{Pipe} keeps no references to it
-whatsoever; all access is mediated by the \type{Output\_Buffers}.
-This allows queues which have been read to be deleted, rather than
-leaving empty queue objects all over the place.
-
-\section{Library Initialization}
-
-WRITEME
-
-\section{Lookup Mechanism}
-
-Most objects know their name, and they know how to create a new copy
-of themselves. We build mapping tables that map from an algorithm name
-into a single instance of that algorithm. The tables themselves can be
-found in \filename{src/lookup.cpp}.
-
-There are a set of functions named \function{add\_algorithm} that can
-be used to populate the tables. We get something out of the table with
-\function{retrieve\_x}, where x is the name of a type
-(\texttt{block\_cipher}, \texttt{hash}, etc). This returns a const
-pointer to the single unique instance of the algorithm that the lookup
-tables know about. If it doesn't know about it, it falls back on
-calling a function called \function{try\_to\_get\_x}. These functions
-live in \filename{src/algolist.cpp}. They are mostly used to handle
-algorithms which need (or at least can have) arguments passed to them,
-like \type{HMAC} and \type{SAFER\_SK}. It will return NULL if it can't
-find the algorithm at all.
-
-When it's asked for an algorithm it doesn't know about (ie, isn't in
-the mapping tables), the retrieval functions will ask the try-to-get
-functions if \emph{they} know about it. If they do, then the object
-returned will be stored into the table for later retrieval.
-
-The functions \function{get\_x} call the retrieval functions. If we
-get back NULL, an exception is thrown. Otherwise it will call the
-\function{clone} method to get a new copy of the algorithm, which it
-returns.
-
-The various functions like \function{output\_length\_of} call the
-retrieval function for each type of object that the parameter in
-question (in this case, \texttt{OUTPUT\_LENGTH}) might be meaningful
-for. If it manages to get back an object, it will return (in this
-case) the \texttt{OUTPUT\_LENGTH} field of the object. No allocations
-are required to call this function: all of its operations work
-directly on the copies living in the lookup tables.
-
-\section{Allocators}
-
-A big (slow) mess.
-
-\section{BigInt}
-
-Read ``Handbook of Applied Cryptography''.
-
-\section{PEM/BER Identification}
-
-We have a specific algorithm for figuring out if something is PEM or
-BER. Previous versions (everything before 1.3.0) requried that the
-caller specify which one it was, and they had to be right. Now we use
-a hueristic (aka, an algorithm that sometimes doesn't work right) to
-figure it out. If the first character is not 0x30 (equal to ASCII
-'0'), then it can't possibly be BER (because everything we care about
-is enclosed in an ASN.1 SEQUENCE, which for BER/DER is encoded as
-beginning with 0x30). Roughly 99.9% of PEM blocks \emph{won't} have a
-random 0 character in front of them, so we are mostly safe (unless
-someone does it on purpose, in which case, please hit them for me).
-But to be sure, if there is a 0, then we search the first \emph{N}
-bytes of the block for the string ``-----BEGIN ``, which marks the
-typical start of a PEM block. The specific \emph{N} depends on the
-variable ``base/pem\_search'', which defaults to 4 kilobytes.
-
-So, you can actually fool it either way: that a PEM file is really
-BER, or that a BER file is actually PEM. To fool it that a BER file is
-PEM, just have the string ``-----BEGIN `` somewhere (I can't imagine
-this string shows up in certificates or CRLs too often, so if it is
-there it means somebody is being a jerk). If a file starts with 0 and
-has at least ``base/pem\_search'' byte more junk in the way, it won't
-notice that its PEM at all. In either case, of course, the loading
-will fail, and you'll get a nice exception saying that the decoding
-failed.
-
-\end{document}
diff --git a/doc/intro.txt b/doc/intro.txt
new file mode 100644
index 000000000..c9a153563
--- /dev/null
+++ b/doc/intro.txt
@@ -0,0 +1,169 @@
+
+Introduction
+=================================
+
+Botan is a C++ library that attempts to provide the most common
+cryptographic algorithms and operations in an easy to use, efficient,
+and portable way. It runs on a wide variety of systems, and can be
+used with most modern C++ compilers.
+
+It is released under the 2 clause BSD license and can be used by
+commercial and open source software; see :ref:`license` for the
+specifics.
+
+The base library is written in ISO C++, so it can be ported with
+minimal fuss, but a modules system is also used. This system exposes
+system dependent code to the library through portable interfaces,
+extending the set of services available to users.
+
+The primary system targets are 32 and 64 bit CPUs, with a flat memory
+address space of at least 32 bits. Given the choice between optimizing
+for 32 bit systems and 64 bit systems, 64 bit is preferred, on the
+general theory that where performance is a real concern, modern 64 bit
+processors are the obvious choice. Smaller devices like handhelds,
+settop boxes, and smart phones are also capable of using Botan.
+
+The design makes it quite easy to remove unused algorithms in such a
+way that applications do not need to be recompiled to work, even
+applications that use the algorithm in question. They can ask the
+library if the algorithm exists, and if so, retrieve an object
+implementing that algorithm.
+
+Recommended Reading
+---------------------------------
+
+It's a very good idea if you have some knowledge of cryptography
+*before* trying to use the library. This is an area where it is very
+easy to make mistakes, and where things are often subtle and/or
+counterintuitive. Obviously the library tries to provide things at
+a high level precisely to minimize the number of ways things can go
+wrong, but naive use will almost certainly not result in a secure
+system.
+
+Especially recommended are:
+
+ - *Cryptography Engineering*
+   Niels Ferguson, Bruce Schneier, and Tadayoshi Kohno
+
+ - *Security Engineering -- A Guide to Building Dependable Distributed Systems*
+   Ross Anderson
+
+ - *Handbook of Applied Cryptography* Alfred J. Menezes, Paul C. Van
+   Oorschot, and Scott A. Vanstone (available online at
+   http://www.cacr.math.uwaterloo.ca/hac/)
+
+Getting Help
+----------------------------------------
+
+Questions or problems you have with Botan can be directed to the
+`development mailing list
+<http://lists.randombit.net/mailman/listinfo/botan-devel/>`_.
+"Philosophical" bug reports, announcements of programs using Botan,
+and anything else having to do with Botan are also welcome.
+
+If you find what you believe to be a bug, please file a ticket in
+`Bugzilla <http://bugs.randombit.net/>`_.
+
+Getting Started
+---------------------------------
+
+All declarations in the library are contained within the namespace
+``Botan``, so you need to either prefix types with ``Botan::`` or add
+a ``using`` declaration in your code. All examples will assume a
+``using`` declaration.
+
+All library headers are included like so::
+
+  #include <botan/botan.h>
+
+Initializing the Library
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is a set of core services that the library needs access to while
+it is performing requests. To ensure these are set up, you must create
+a ``LibraryInitializer`` object (usually called 'init' in Botan
+example code; 'botan\_library' or 'botan\_init' may make more sense in
+real applications) prior to making any calls to Botan. This object's
+lifetime must exceed that of all other Botan objects your application
+creates; for this reason the best place to create the
+``LibraryInitializer`` is at the start of your ``main``
+function, since this guarantees that it will be created first and
+destroyed last (via standard C++ RAII rules). The initializer does
+things like setting up the memory allocation system and algorithm
+lookup tables, finding out if there is a high resolution timer
+available to use, and similar such matters. With no arguments, the
+library is initialized with various default settings. So (unless you
+are writing threaded code; see below), all you need is::
+
+   Botan::LibraryInitializer init;
+
+at the start of your ``main``.
+
+The constructor takes an optional string that specifies arguments.
+Currently the only possible argument is "thread_safe", which must have
+an boolean argument (for instance "thread_safe=false" or
+"thread_safe=true"). If "thread_safe" is specified as true the library
+will attempt to register a mutex type to properly guard access to
+shared resources. However these locks do not protect individual Botan
+objects: explicit locking must be used if you wish to share a single
+object between threads.
+
+If you do not create a ``LibraryInitializer`` object, all library
+operations will fail, because it will be unable to do basic things
+like allocate memory or get random bits. You should never create more
+than one ``LibraryInitializer``.
+
+Pitfalls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are a few things to watch out for to prevent problems when using
+the library.
+
+Never allocate any kind of Botan object globally. The problem with
+doing this is that the constructor for such an object will be called
+before the library is initialized. Many Botan objects will, in their
+constructor, make one or more calls into the library global state
+object. Access to this object is checked, so an exception should be
+thrown (rather than a memory access violation or undetected
+uninitialized object access). A rough equivalent that will work is to
+keep a global pointer to the object, initializing it after creating
+your ``LibraryInitializer``. Merely making the
+``LibraryInitializer`` also global will probably not help, because
+C++ does not make very strong guarantees about the order that such
+objects will be created.
+
+The same rule applies for making sure the destructors of all your
+Botan objects are called before the ``LibraryInitializer`` is
+destroyed. This implies you can't have static variables that are Botan
+objects inside functions or classes; in many C++ runtimes, these
+objects will be destroyed after main has returned.
+
+The memory object classes (``MemoryRegion``, ``MemoryVector``,
+``SecureVector``) are extremely primitive, and meant only for
+secure storage of potentially sensitive data like keys. They do not
+meet the requirements for an STL container object and you should not
+try to use them with STL algorithms. For a general-purpose container,
+use ``std::vector``.
+
+Use a ``try``/``catch`` block inside your ``main`` function, and catch
+any ``std::exception`` throws (remember to catch by reference, as
+``std::exception::what`` is polymorphic)::
+
+  int main()
+     {
+     try
+        {
+        LibraryInitializer init;
+
+        // ...
+        }
+     catch(std::exception& e)
+        {
+        std::cerr << e.what() << "\n";
+        }
+     }
+
+This is not strictly required, but if you don't, and Botan throws an
+exception, the runtime will call ``std::terminate``, which usually
+calls ``abort`` or something like it, leaving you (or worse, a user of
+your application) wondering what went wrong.
diff --git a/doc/license.txt b/doc/license.txt
index f1b261eab..33b2f5982 100644
--- a/doc/license.txt
+++ b/doc/license.txt
@@ -1,42 +1,48 @@
-Botan (http://botan.randombit.net/) is distributed under these terms:
-
-Copyright (C) 1999-2011 Jack Lloyd
-              2001 Peter J Jones
-              2004-2007 Justin Karneges
-              2004 Vaclav Ovsik
-              2005 Matthew Gregan
-              2005-2006 Matt Johnston
-              2006 Luca Piccarreta
-              2007 Yves Jerschow
-              2007-2008 FlexSecure GmbH
-              2007-2008 Technische Universitat Darmstadt
-              2007-2008 Falko Strenzke
-              2007-2008 Martin Doering
-              2007 Manuel Hartl
-              2007 Christoph Ludwig
-              2007 Patrick Sona
-              2010 Olivier de Gaalon
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-1. Redistributions of source code must retain the above copyright
-notice, this list of conditions, and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright
-notice, this list of conditions, and the following disclaimer in the
-documentation and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
-IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
-ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
-IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+.. _license:
+
+License
+========================================
+
+Botan (http://botan.randombit.net/) is distributed under these terms::
+
+  Copyright (C) 1999-2011 Jack Lloyd
+                2001 Peter J Jones
+                2004-2007 Justin Karneges
+                2004 Vaclav Ovsik
+                2005 Matthew Gregan
+                2005-2006 Matt Johnston
+                2006 Luca Piccarreta
+                2007 Yves Jerschow
+                2007-2008 FlexSecure GmbH
+                2007-2008 Technische Universitat Darmstadt
+                2007-2008 Falko Strenzke
+                2007-2008 Martin Doering
+                2007 Manuel Hartl
+                2007 Christoph Ludwig
+                2007 Patrick Sona
+                2010 Olivier de Gaalon
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are
+  met:
+
+  1. Redistributions of source code must retain the above copyright
+  notice, this list of conditions, and the following disclaimer.
+
+  2. Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions, and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+  THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
+  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
+  ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
+  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+  BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
+  IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/doc/log.txt b/doc/log.txt
index 8ceb13a60..d4dd96430 100644
--- a/doc/log.txt
+++ b/doc/log.txt
@@ -1,1545 +1,1884 @@
 
-* 1.9.16-dev, ????-??-??
- - Second release candidate for 1.10.0
- - Disable the by-default 'strong' checking of private keys that are
-   loaded from storage. You can always request key material sanity
-   checking using check_key.
- - Bring back removed functions min_keylength_of, max_keylength_of,
-   keylength_multiple_of in lookup.h to avoid breaking applications.
-
-* 1.9.15, 2011-03-21
- - First release candidate for 1.10.0
- - Modify how message expansion is done in SHA-256 and SHA-512.
-   Instead of expanding the entire message at the start, compute them
-   in the minimum number of registers. Values are computed 15 rounds
-   before they are needed. On a Core i7-860, GCC 4.5.2, went from
-   143 to 157 MiB/s in SHA-256, and 211 to 256 MiB/s in SHA-512.
- - Pipe will delete empty output queues as soon as they are no longer
-   needed, even if earlier messages still have data unread. However an
-   (empty) entry in a deque of pointers will remain until all prior
-   messages are completely emptied.
- - Avoid reading the SPARC %tick register on OpenBSD as unlike Linux
-   the kernel will not trap and emulate it for us, causing a illegal
-   instruction crash.
- - Improve detection and autoconfiguration for ARM processors.
-
-* 1.9.14, 2011-03-01
- - Add support for bcrypt, OpenBSD's password hashing scheme
- - Add support for NIST's AES key wrapping algorithm
- - Fix an infinite loop in zlib filters introduced in 1.9.11 (PR 142)
-
-* 1.9.13, 2011-02-19
- - Update Keccak to the round 3 variant
- - Fix ordering in GOST 34.10 signatures to match DNSSEC specifications
- - Use size_t instead of u32bit for small integers in DER/BER codecs
- - Add new build option --distribution-info
- - Fix problems in the amalgamation build
- - Fix building under Clang 2.9 and Sun Studio 12
-
-* 1.9.12, 2010-12-13
- - Add the Keccak hash function
- - Fix compilation problems in Python wrappers
- - Fix compilation problem in OpenSSL engine
- - Update SQLite3 database encryption codec
-
-* 1.9.11, 2010-11-29
- - Many SSL/TLS APIs have changed. This API is still unstable.
- - The SSL interface requires TR1 (uses std::tr1::function)
- - Fix SSL handshake failures when using RC4 ciphersuites
- - Fix a number of CRL encoding and decoding bugs
- - Counter mode now always encrypts 256 blocks in parallel
- - Code where u32bit was used to represent a length now uses size_t
- - Use small tables in the first round of AES
- - Removed AES class: app must choose AES-128, AES-192, or AES-256
- - Add hex encoding/decoding functions that can be used without a Pipe
- - Add base64 encoding functions that can be used without a Pipe
- - Add to_string function to X509_Certificate
- - Add support for dynamic engine loading on Windows
- - Replace BlockCipher::BLOCK_SIZE attribute with function block_size()
- - Replace HashFunction::HASH_BLOCK_SIZE attribute with hash_block_size()
- - Changed semantics of MemoryRegion::resize and clear to match STL
- - Removed MemoryRegion::append, replaced by push_back and operator+=
- - Move PBKDF lookup to engine system
- - The IDEA key schedule has been changed to run in constant time
- - Avoid a possible timing vulnerability in Montgomery reduction
- - Add Algorithm and Key_Length_Specification classes
- - Switch default PKCS #8 encryption algorithm from AES-128 to AES-256
- - Update Skein-512 to match the v1.3 specification
- - Allow using PBKDF2 with empty passphrases
- - Add compile-time deprecation warnings for GCC, Clang, and MSVC
- - Support use of HMAC(SHA-256) and CMAC(Blowfish) in passhash9
- - Improve support for Intel Atom processors
- - Fix compilation problems under Sun Studio and Clang
-
-* 1.8.11, 2010-11-02
- - Fix a number of CRL encoding and decoding bugs
- - When building a debug library under VC++, use the debug runtime
- - Fix compilation under Sun Studio on Linux and Solaris
- - Add several functions for compatability with 1.9
- - In the examples, read most input files as binary
- - The Perl build script has been removed in this release
-
-* 1.8.10, 2010-08-31
- - Switch default PKCS #8 encryption algorithm from 3DES to AES-256
- - Increase default hash iterations from 2048 to 10000 in PBES1 and PBES2
- - Use small tables in the first round of AES
- - Add PBKDF typedef and get_pbkdf for better compatability with 1.9
- - Add version of S2K::derive_key taking salt and iteration count
- - Enable the /proc-walking entropy source on NetBSD
- - Fix the doxygen makefile target
-
-* 1.9.10, 2010-08-12
- - Add a constant time AES implementation using SSSE3
- - Add support for loading new Engines at runtime
- - Use GCC byteswap intrinsics where possible
- - Drop support for building with Python 2.4
- - Fix benchmarking of block ciphers in ECB mode
- - Consolidate the two x86 assembly engines
- - Rename S2K to PBKDF
-
-* 1.9.9, 2010-06-28
- - Add new X509::BER_encode and PKCS8::BER_encode
- - Give all Filter objects a name() function
- - Add Keyed_Filter::valid_iv_length
- - Increase default iteration counts for private key encryption
- - Fix compilation of mp_asm64 on 64-bit MIPS with GCC 4.4 and later
- - Fix compilation under Apple's GCC 4.2
- - Expand and update the Doxygen documentation
-
-* 1.8.9, 2010-06-16
- - Use constant time multiplication in IDEA
- - Avoid possible timing attack against OAEP decoding
- - Add new X509::BER_encode and PKCS8::BER_encode
- - Enable DLL builds under Windows
- - Add Win32 installer support
- - Add support for the Clang compiler
- - Fix problem in semcem.h preventing build under Clang or GCC 3.4
- - Fix bug that prevented creation of DSA groups under 1024 bits
- - Fix crash in GMP_Engine if library is shutdown and reinitialized
- - Work around problem with recent binutils in x86-64 SHA-1
- - The Perl build script is no longer supported and refuses to run by default
-
-* 1.9.8, 2010-06-14
- - Add support for wide multiplications on 64-bit Windows
- - Use constant time multiplication in IDEA
- - Avoid possible timing attack against OAEP decoding
- - Removed FORK-256; rarely used and it has been broken
- - Rename --use-boost-python to --with-boost-python
- - Skip building shared libraries on MinGW/Cygwin
- - Fix creation of 512 and 768 bit DL groups using the DSA kosherizer
- - Fix compilation on GCC versions before 4.3 (missing cpuid.h)
- - Fix compilation under the Clang compiler
-
-* 1.9.7, 2010-04-27
- - TLS: Support reading SSLv2 client hellos
- - TLS: Add support for SEED ciphersuites (RFC 4162)
- - Add Comb4P hash combiner function
- - Fix checking of EMSA_Raw signatures with leading 0 bytes
-
-* 1.9.6, 2010-04-09
- - TLS: Add support for TLS v1.1
- - TLS: Support server name indicator extension
- - TLS: Fix server handshake
- - TLS: Fix server using DSA certificates
- - TLS: Avoid timing channel between CBC padding check and MAC verification
-
-* 1.9.5, 2010-03-29
- - Numerous ECC optimizations
- - Fix GOST 34.10-2001 X.509 key loading
- - Allow PK_Signer's fault protection checks to be toggled off
- - Avoid using pool-based locking allocator if we can't mlock
- - Remove all runtime options
- - New BER_Decoder::{decode_and_check, decode_octet_string_bigint}
- - Remove SecureBuffer in favor of SecureVector length parameter
- - HMAC_RNG: Perform a poll along with user-supplied entropy
- - Fix crash in MemoryRegion if Allocator::get failed
- - Fix small compilation problem on FreeBSD
-
-* 1.9.4, 2010-03-09
- - Add the Ajisai SSLv3/TLSv1.0 implementation
- - Add GOST 34.10-2001 public key signature scheme
- - Add SIMD implementation of Noekeon
- - Add SSE2 implementation of IDEA
- - Extend Salsa20 to support longer IVs (XSalsa20)
- - Perform XTS encryption and decryption in parallel where possible
- - Perform CBC decryption in parallel where possible
- - Add SQLite3 db encryption codec, contributed by Olivier de Gaalon
- - Add a block cipher cascade construction
- - Add support for password hashing for authentication (passhash9.h)
- - Add support for Win32 high resolution system timers
- - Major refactoring and API changes in the public key code
- - Use consistency checking (anti-fault attack) for all signature schemes
- - Changed S2K interface: derive_key now takes salt, iteration count
- - Remove dependency on TR1 for ECC and CVC code
- - Renamed ECKAEG to its more usual name, ECDH
- - Fix crash in GMP_Engine if library is shutdown and reinitialized
- - Fix an invalid memory read in MD4
- - Fix Visual C++ static builds
- - Remove Timer class entirely
- - Switch default PKCS #8 encryption algorithm from 3DES to AES-128
- - New option --gen-amalgamation for creating a SQLite-style amalgamation
- - Many headers are now explicitly internal-use-only and are not installed
- - Greatly improve the Win32 installer
- - Several fixes for Visual C++ debug builds
-
-* 1.9.3, 2009-11-19
- - Add new AES implementation using Intel's AES instruction intrinsics
- - Add an implementation of format preserving encryption
- - Allow use of any hash function in X.509 certificate creation
- - Optimizations for MARS, Skipjack, and AES
- - Set macros for available SIMD instructions in build.h
- - Add support for using InnoSetup to package Windows builds
- - By default build a DLL on Windows
-
-* 1.9.2, 2009-11-03
- - Add SIMD version of XTEA
- - Support both SSE2 and AltiVec SIMD for Serpent and XTEA
- - Optimizations for SHA-1 and SHA-2
- - Add AltiVec runtime detection
- - Fix x86 CPU identification with Intel C++ and Visual C++
-
-* 1.8.8, 2009-11-03
- - Alter Skein-512 to match the tweaked 1.2 specification
- - Fix use of inline asm for access to x86 bswap function
- - Allow building the library without AES enabled
- - Add 'powerpc64' alias to ppc64 arch for Gentoo ebuild
-
-* 1.9.1, 2009-10-23
- - Better support for Python and Perl wrappers
- - Add an implementation of Blue Midnight Wish (Round 2 tweak version)
- - Modify Skein-512 to match the tweaked 1.2 specification
- - Add threshold secret sharing (draft-mcgrew-tss-02)
- - Add runtime cpu feature detection for x86/x86-64
- - Add code for general runtime self testing for hashes, MACs, and ciphers
- - Optimize XTEA; twice as fast as before on Core2 and Opteron
- - Convert CTR_BE and OFB from filters to stream ciphers
- - New parsing code for SCAN algorithm names
- - Enable SSE2 optimizations under Visual C++
- - Remove all use of C++ exception specifications
- - Add support for GNU/Hurd and Clang/LLVM
-
-* 1.9.0, 2009-09-09
- - Add support for parallel invocation of block ciphers where possible
- - Add SSE2 implementation of Serpent
- - Add Rivest's package transform (an all or nothing transform)
- - Minor speedups to the Turing key schedule
- - Fix processing multiple messages in XTS mode
- - Add --no-autoload option to configure.py, for minimized builds
- - The previously used configure.pl script is no longer supported
-
-* 1.8.7, 2009-09-09
- - Fix processing multiple messages in XTS mode
- - Add --no-autoload option to configure.py, for minimized builds
-
-* 1.8.6, 2009-08-13
- - Add Cryptobox, a set of simple password-based encryption routines
- - Only read world-readable files when walking /proc for entropy
- - Fix building with TR1 disabled
- - Fix x86 bswap support for Visual C++
- - Fixes for compilation under Sun C++
- - Add support for Dragonfly BSD (contributed by Patrick Georgi)
- - Add support for the Open64 C++ compiler
- - Build fixes for MIPS systems running Linux
- - Minor changes to license, now equivalent to the FreeBSD/NetBSD license
-
-* 1.8.5, 2009-07-23
- - Change configure.py to work on stock Python 2.4
- - Avoid a crash in Skein_512::add_data processing a zero-length input
- - Small build fixes for SPARC, ARM, and HP-PA processors
- - The test suite now returns an error code from main() if any tests failed
-
-* 1.8.4, 2009-07-12
- - Fix a bug in nonce generation in the Miller-Rabin test
-
-* 1.8.3, 2009-07-11
- - Add a new Python configuration script
- - Add the Skein-512 SHA-3 candidate hash function
- - Add the XTS block cipher mode from IEEE P1619
- - Fix random_prime when generating a prime of less than 7 bits
- - Improve handling of low-entropy situations during PRNG seeding
- - Change random device polling to prefer /dev/urandom over /dev/random
- - Use an input insensitive implementation of same_mem instead of memcmp
- - Correct DataSource::discard_next to return the number of discarded bytes
- - Provide a default value for AutoSeeded_RNG::reseed
- - Fix Gentoo bug 272242
-
-* 1.8.2, 2009-04-07
- - Make entropy polling more flexible and in most cases faster
- - GOST 28147 now supports multiple sbox parameters
- - Added the GOST 34.11 hash function
- - Fix botan-config problems on MacOS X
-
-* 1.8.1, 2009-01-20
- - Avoid a valgrind warning in es_unix.cpp on 32-bit Linux
- - Fix memory leak in PKCS8 load_key and encrypt_key
- - Relicense api.tex from CC-By-SA 2.5 to BSD
- - Fix botan-config on MacOS X, Solaris
-
-* 1.8.0, 2008-12-08
- - Fix compilation on Solaris with GCC
-
-* 1.7.24, 2008-12-01
- - Fix a compatibility problem with SHA-512/EMSA3 signature padding
- - Fix bug preventing EGD/PRNGD entropy poller from working
- - Fix integer overflow in Pooling_Allocator::get_more_core (bug id #27)
- - Add EMSA3_Raw, a variant of EMSA3 called CKM_RSA_PKCS in PKCS #11
- - Add support for SHA-224 in EMSA2 and EMSA3 PK signature padding schemes
- - Add many more test vectors for RSA with EMSA2, EMSA3, and EMSA4
- - Wrap private structs in SSE2 SHA-1 code in anonymous namespace
- - Change configure.pl's CPU autodetection output to be more consistent
- - Disable using OpenSSL's AES due to crashes of unknown cause
- - Fix warning in /proc walking entropy poller
- - Fix compilation with IBM XLC for Cell 0.9-200709
-
-* 1.7.23, 2008-11-23
- - Change to use TR1 (thus enabling ECDSA) with GCC and ICC
- - Optimize almost all hash functions, especially MD4 and Tiger
- - Add configure.pl options --{with,without}-{bzip2,zlib,openssl,gnump}
- - Change Timer to be pure virtual, and add ANSI_Clock_Timer
- - Cache socket descriptors in the EGD entropy source
- - Avoid bogging down startup in /proc walking entropy source
- - Remove Buffered_EntropySource helper class
- - Add a Default_Benchmark_Timer typedef in benchmark.h
- - Add examples using benchmark.h and Algorithm_Factory
- - Add ECC tests from InSiTo
- - Minor documentation updates
-
-* 1.7.22, 2008-11-17
- - Add provider preferences to Algorithm_Factory
- - Fix memory leaks in PBE_PKCS5v20 and get_pbe introduced in 1.7.21
- - Optimize AES encryption and decryption (about 10% faster)
- - Enable SSE2 optimized SHA-1 implementation on Intel Prescott CPUs
- - Fix nanoseconds overflow in benchmark code
- - Remove Engine::add_engine
-
-* 1.7.21, 2008-11-11
- - Make algorithm lookup much more configuable
- - Add facilities for runtime performance testing of algorithms
- - Drop use of entropy estimation in the PRNGs
- - Increase intervals between HMAC_RNG automatic reseeding
- - Drop InitializerOptions class, all options but thread safety
-
-* 1.7.20, 2008-11-09
- - Namespace pkg-config file by major and minor versions
- - Cache device descriptors in Device_EntropySource
- - Split base.h into {block_cipher,stream_cipher,mac,hash}.h
- - Removed get_mgf function from lookup.h
-
-* 1.7.19, 2008-11-06
- - Add HMAC_RNG, based on a design by Hugo Krawczyk
- - Optimized the Turing stream cipher (about 20% faster on x86-64)
- - Modify Randpool's reseeding algorithm to poll more sources
- - Add a new AutoSeeded_RNG in auto_rng.h
- - OpenPGP_S2K changed to take hash object instead of name
- - Add automatic identification for Intel's Prescott processors
-
-* 1.7.18, 2008-10-22
- - Add Doxygen comments from InSiTo
- - Add ECDSA and ECKAEG benchmarks
- - Add configure.pl switch --with-tr1-implementation
- - Fix configure.pl's --with-endian and --with-unaligned-mem options
- - Added support for pkg-config
- - Optimize byteswap with x86 inline asm for Visual C++ by Yves Jerschow
- - Use const references to avoid copying overhead in CurveGFp, GFpModulus
-
-* 1.7.17, 2008-10-12
- - Add missing ECDSA object identifiers
- - Fix error in x86 and x86-64 assembler affecting GF(p) math
- - Remove Boost dependency from GF(p) math
- - Modify botan-config to not print -L/usr/lib or -L/usr/local/lib
- - Add BOTAN_DLL macro to over 30 classes missing it
- - Rename the two SHA-2 base classes for consistency
-
-* 1.7.16, 2008-10-09
- - Add several missing pieces needed for ECDSA and ECKAEG
- - Add Card Verifiable Certificates from InSiTo
- - Add SHA-224 from InSiTo
- - Add BSI variant of EMSA1 from InSiTo
- - Add GF(p) and ECDSA tests from InSiTo
- - Split ECDSA and ECKAEG into distinct modules
- - Allow OpenSSL and GNU MP engines to be built with public key algos disabled
- - Rename sha256.h to sha2_32.h and sha_64.h to sha2_64.h
-
-* 1.7.15, 2008-10-07
- - Add GF(p) arithmetic from InSiTo
- - Add ECDSA and ECKAEG implementations from InSiTo
- - Minimize internal dependencies, allowing for smaller build configurations
- - Add new User Manual and Architecture Guide from FlexSecure GmbH
- - Alter configure.pl options for better autotools compatibility
- - Update build instructions for recent changes to configure.pl
- - Fix CPU detection using /proc/cpuinfo
-
-* 1.7.14, 2008-09-30
- - Split library into parts allowing modular builds
- - Add (very preliminary) CMS support to the main library
- - Some constructors now require object pointers instead of names
- - Support multiple implementations of the same algorithm
- - Build support for Pentium-M processors, from Derek Scherger
- - Build support for MinGW/MSYS, from Zbigniew Zagorski
- - Use inline assembly for bswap on 32-bit x86
-
-* 1.7.13, 2008-09-27
- - Add SSLv3 MAC, SSLv3 PRF, and TLS v1.0 PRF from Ajisai
- - Allow all examples to compile even if compression not enabled
- - Make CMAC's polynomial doubling operation a public class method
- - Use the -m64 flag when compiling with Sun Forte on x86-64
- - Clean up and slightly optimize CMAC::final_result
-
-* 1.7.12, 2008-09-18
- - Add x86 assembly for Visual Studio C++, by Luca Piccarreta
- - Add a Perl XS module, by Vaclav Ovsik
- - Add SWIG-based wrapper for Botan
- - Add SSE2 implementation of SHA-1, by Dean Gaudet
- - Remove the BigInt::sig_words cache due to bugs
- - Combined the 4 Blowfish sboxes, suggested by Yves Jerschow
- - Changed BigInt::grow_by and BigInt::grow_to to be non-const
- - Add private assignment operators to classes that don't support assignment
- - Benchmark RSA encryption and signatures
- - Added test programs for random_prime and ressol
- - Add high resolution timers for IA-64, HP-PA, S390x
- - Reduce use of the RNG during benchmarks
- - Fix builds on STI Cell PPU
- - Add support for IBM's XLC compiler
- - Add IETF 8192 bit MODP group
-
-* 1.7.11, 2008-09-11
- - Added the Salsa20 stream cipher
- - Optimized Montgomery reduction, Karatsuba squaring
- - Added 16x16->32 word Comba multiplication and squaring
- - Use a much larger Karatsuba cutoff point
- - Remove bigint_mul_add_words
- - Inlined several BigInt functions
- - Add useful information to the generated build.h
- - Rename alg_{ia32,amd64} modules to asm_{ia32,amd64}
- - Fix the Windows build
-
-* 1.7.10, 2008-09-05
- - Public key benchmarks run using a selection of random keys
- - New benchmark timer options are clock_gettime, gettimeofday, times, clock
- - Including reinterpret_cast optimization for xor_buf in default header
- - Split byte swapping and word rotation functions into distinct headers
- - Add IETF modp 6144 group and 2048 and 3072 bit DSS groups
- - Optimizes BigInt right shift
- - Add aliases in DL_Group::Format enum
- - BigInt now caches the significant word count
-
-* 1.7.9, 2008-08-27
- - Make clear() in most algorithm base classes a pure virtual
- - Add noexec stack marker for GNU linker in assembly code
- - Avoid string operations in ressol
- - Compilation fixes for MinGW and Visual Studio C++ 2008
- - Some autoconfiguration fixes for Windows
-
-* 1.6.5, 2008-08-27
- - Add noexec stack marker for GNU linker in assembly code
- - Fix autoconfiguration problem on x86 with GCC 4.2 and 4.3
-
-* 1.7.8, 2008-07-15
- - Added the block cipher Noekeon
- - Remove global deref_alias function
- - X509_Store takes timeout options as constructor arguments
- - Add Shanks-Tonelli algorithm, contributed by FlexSecure GmbH
- - Extend random_prime() for generating primes of any bit length
- - Remove Config class
- - Allow adding new entropy via base RNG interface
- - Reseeding a X9.31 PRNG also reseeds the underlying PRNG
-
-* 1.7.7, 2008-06-28
- - Remove the global PRNG object
- - The PK filter objects were removed
- - Add a test suite for the ANSI X9.31 PRNG
- - Much cleaner and (mostly) thread-safe reimplementation of es_ftw
- - Remove both default arguments to ANSI_X931_RNG's constructor
- - Remove the randomizing version of OctetString::change
- - Make the cipher and MAC to use in Randpool configurable
- - Move RandomNumberGenerator declaration to rng.h
- - RSA_PrivateKey will not generate keys smaller than 1024 bits
- - Fix an error decoding BER UNIVERSAL types with special taggings
-
-* 1.7.6, 2008-05-05
- - Initial support for Windows DLLs, from Joel Low
- - Reset the position pointer when a new block is generated in X9.32 PRNG
- - Timer objects are now treated as entropy sources
- - Moved several ASN.1-related enums from enums.h to an appropriate header
- - Removed the AEP module, due to inability to test
- - Removed Global_RNG and rng.h
- - Removed system_clock
- - Removed Library_State::UI and the pulse callback logic
-
-* 1.7.5, 2008-04-12
- - The API of X509_CA::sign_request was altered to avoid race conditions
- - New type Pipe::message_id to represent the Pipe message number
- - Remove the Named_Mutex_Holder for a small performance gain
- - Removed several unused or rarely used functions from Config
- - Ignore spaces inside of a decimal string in BigInt::decode
- - Allow using a std::istream to initialize a DataSource_Stream object
- - Fix compilation problem in zlib compression module
- - The chunk sized used by Pooling_Allocator is now a compile time setting
- - The size of random blinding factors is now a compile time setting
- - The install target no longer tries to set a particular owner/group
-
-* 1.7.4, 2008-03-10
- - Use unaligned memory read/writes on systems that allow it, for performance
- - Assembly for x86-64 for accessing the bswap instruction
- - Use larger buffers in ARC4 and WiderWAKE for significant throughput increase
- - Unroll loops in SHA-160 for a few percent increase in performance
- - Fix compilation with GCC 3.2 in es_ftw and es_unix
- - Build fix for NetBSD systems
- - Prevent es_dev from being built except on Unix systems
-
-* 1.6.4, 2008-03-08
- - Fix a compilation problem with Visual Studio C++ 2003
-
-* 1.7.3, 2008-01-23
- - New invocation syntax for configure.pl with several new options
- - Support for IPv4 addresses in a subject alternative name
- - New fast poll for the generic Unix entropy source (es_unix)
- - The es_file entropy source has been replaced by the es_dev module
- - The malloc allocator does not inherit from Pooling_Allocator anymore
- - The path that es_unix will search in are now fully user-configurable
- - Truncate X9.42 PRF output rather than allow counter overflow
- - PowerPC is now assumed to be big-endian
-
-* 1.7.2, 2007-10-13
- - Initialize the global library state lazily
- - Add plain CBC-MAC for backwards compatibility with old systems
- - Clean up some of the self test code
- - Throw a sensible exception if a DL_Group is not found
- - Truncate KDF2 output rather than allowing counter overflow
- - Add newly assigned OIDs for SHA-2 and DSA with SHA-224/256
- - Fix a Visual Studio compilation problem in x509stat.cpp
-
-* 1.7.1, 2007-07-23
- - Fix a race condition in the algorithm object cache
- - HMAC key schedule optimization
- - The build header sets a macro defining endianness, if known
- - New word load/store abstraction allowing further optimization
- - Modify most of the library to avoid use the C-style casts
- - Use higher resolution timers in symmetric benchmarks
-
-* 1.6.3, 2007-07-23
- - Fix a race condition in the algorithm lookup cache
- - Fix problems building the memory pool on some versions of Visual C++
-
-* 1.7.0, 2007-05-19
- - DSA parameter generation now follows FIPS 186-3
- - Added OIDs for Rabin-Williams and Nyberg-Rueppel
- - Somewhat better support for out of tree builds
- - Minor optimizations for RC2 and Tiger
- - Documentation updates
- - Update the todo list
-
-* 1.6.2, 2007-03-24
- - Fix autodection on Athlon64s running Linux
- - Fix builds on QNX and compilers using STLport
- - Remove a call to abort() that crept into production
-
-* 1.6.1, 2007-01-20
- - Fix some base64 decoder bugs
- - Add a new option to base64 encoding, to always append a newline
- - Fix some build problems under Visual Studio with debug enabled
- - Fix a bug in BER_Decoder that was triggered under some compilers
-
-* 1.6.0, 2006-12-17
- - Minor cleanups versus 1.5.13
-
-* 1.5.13, 2006-12-10
- - Compilation fixes for the bzip2, zlib, and GNU MP modules
- - Better support for Intel C++ and EKOpath C++ on x86-64
-
-* 1.5.12, 2006-10-27
- - Cleanups in the initialization routines
- - Add some x86-64 assembly for multiply-add
- - Fix problems generating very small (below 384 bit) RSA keys
- - Support out of tree builds
- - Bring some of the documentation up to date
- - More improvements to the Python bindings
-
-* 1.5.11, 2006-09-10
- - Removed the Algorithm base class
- - Various cleanups in the public key inheritance hierarchy
- - Major overhaul of the configure/build setup
- - Added x86 assembler implementations of Serpent and low-level MPI code
- - Optimizations for the SHA-1 x86 assembler
- - Various improvements to the Python wrappers
- - Work around a Visual Studio compiler bug
-
-* 1.5.10, 2006-08-13
- - Add x86 assembler versions of MD4, MD5, and SHA-1
- - Expand InitializerOptions' language to support on/off switches
- - Fix definition of OID 2.5.4.8; was accidentally changed in 1.5.9
- - Fix possible resource leaks in the mmap allocator
- - Slightly optimized buffering in MDx_HashFunction
- - Initialization failures are dealt with somewhat better
- - Add an example implementing Pollard's Rho algorithm
- - Better option handling in the test/benchmark tool
- - Expand the xor_ciph example to support longer keys
- - Some updates to the documentation
-
-* 1.5.9, 2006-07-12
- - Fixed bitrot in the AEP engine
- - Fix support for marking certificate/CRL extensions as critical
- - Significant cleanups in the library state / initialization code
- - LibraryInitializer takes an explicit InitializerOptions object
- - Make Mutex_Factory an abstract class, add Default_Mutex_Factory
- - Change configuration access to using global_state()
- - Add support for global named mutexes throughout the library
- - Add some STL wrappers for the delete operator
- - Change how certificates are created to be more flexible and general
-
-* 1.5.8, 2006-06-23
- - Many internal cleanups to the X.509 cert/CRL code
- - Allow for application code to support new X.509 extensions
- - Change the return type of X509_Certificate::{subject,issuer}_info
- - Allow for alternate character set handling mechanisms
- - Fix a bug that was slowing squaring performance somewhat
- - Fix a very hard to hit overflow bug in the C version of word3_muladd
- - Minor cleanups to the assembler modules
- - Disable es_unix module on FreeBSD due to build problem on FreeBSD 6.1
- - Support for GCC 2.95.x has been dropped in this release
-
-* 1.5.7, 2006-05-28
- - Further, major changes to the BER/DER coding system
- - Updated the Qt mutex module to use Mutex_Factory
- - Moved the library global state object into an anonymous namespace
- - Drop the Visual C++ x86 assembly module due to bugs
-
-* 1.5.6, 2006-03-01
- - The low-level DER/BER coding system was redesigned and rewritten
- - Portions of the certificate code were cleaned up internally
- - Use macros to substantially clean up the GCC assembly code
- - Added 32-bit x86 assembly for Visual C++ (by Luca Piccarreta)
- - Avoid a couple of spurious warnings under Visual C++
- - Some slight cleanups in X509_PublicKey::key_id
-
-* 1.5.5, 2006-02-04
- - Fixed a potential infinite loop in the memory pool code (Matt Johnston)
- - Made Pooling_Allocator::Memory_Block an actual class of sorts
- - Some small optimizations to the division and modulo computations
- - Cleaned up the implementation of some of the BigInt operators
- - Reduced use of dynamic memory allocation in low-level BigInt functions
- - A few simplifications in the Randpool mixing function
- - Removed power(), as it was not particularly useful (or fast)
- - Fixed some annoying bugs in the benchmark code
- - Added a real credits file
-
-* 1.5.4, 2006-01-29
- - Integrated x86 and amd64 assembly code, contributed by Luca Piccarreta
- - Fixed a memory access off-by-one in the Karatsuba code
- - Changed Pooling_Allocator's free list search to a log(N) algorithm
- - Merged ModularReducer with its only subclass, Barrett_Reducer
- - Fixed sign-handling bugs in some of the division and modulo code
- - Renamed the module description files to modinfo.txt
- - Further cleanups in the initialization code
- - Removed BigInt::add and BigInt::sub
- - Merged all the division-related functions into just divide()
- - Modified the <mp_asmi.h> functions to allow for better optimizations
- - Made the number of bits polled from an EntropySource user configurable
- - Avoid including <algorithm> in <botan/secmem.h>
- - Fixed some build problems with Sun Forte
- - Removed some dead code from bigint_modop
- - Fix the definition of same_mem
-
-* 1.5.3, 2006-01-24
- - Many optimizations in the low-level multiple precision integer code
- - Added hooks for assembly implementations of the MPI code
- - Support for the X.509 issuer alternative name extension in new certs
- - Fixed a bug in the decompression modules; found and patched by Matt Johnston
- - New Windows mutex module (mux_win32), by Luca Piccarreta
- - Changed the Windows timer module to use QueryPerformanceCounter
- - mem_pool.cpp was using std::set iterators instead of std::multiset ones
- - Fixed a bug in X509_CA preventing users from disabling particular extensions
- - Fixed the mp_asm64 module, which was entirely broken in 1.5.2
- - Fixed some module build problems on FreeBSD and Tru64
-
-* 1.5.2, 2006-01-15
- - Fixed an off-by-one memory read in MISTY1::key()
- - Fixed a nasty memory leak in Output_Buffers::retire()
- - Reimplemented the memory allocator from scratch
- - Improved memory caching in Montgomery exponentiation
- - Optimizations for multiple precision addition and subtraction
- - Fixed a build problem in the hardware timer module on 64-bit PowerPC
- - Changed default Karatsuba cutoff to 12 words (was 14)
- - Removed MemoryRegion::bits(), which was unused and incorrect
- - Changed maximum HMAC keylength to 1024 bits
- - Various minor Makefile and build system changes
- - Avoid using std::min in <secmem.h> to bypass Windows libc macro pollution
- - Switched checks/clock.cpp back to using clock() by default
- - Enabled the symmetric algorithm tests, which were accidentally off in 1.5.1
- - Removed the Default_Mutex's unused clone() member function
-
-* 1.4.12, 2006-01-15
- - Fixed an off-by-one memory read in MISTY1::key()
- - Fixed a nasty memory leak in Output_Buffers::retire()
- - Changed maximum HMAC keylength to 1024 bits
- - Fixed a build problem in the hardware timer module on 64-bit PowerPC
-
-* 1.5.1, 2006-01-08
- - Implemented Montgomery exponentiation
- - Implemented generalized Karatsuba multiplication and squaring
- - Implemented Comba squaring for 4, 6, and 8 word inputs
- - Added new Modular_Exponentiator and Power_Mod classes
- - Removed FixedBase_Exp and FixedExponent_Exp
- - Fixed a performance regression in get_allocator introduced in 1.5.0
- - Engines can now offer S2K algorithms and block cipher padding methods
- - Merged the remaining global 'algolist' code into Default_Engine
- - The low-level MPI code is linked as C again
- - Replaced BigInt's get_nibble with the more general get_substring
- - Some documentation updates
-
-* 1.5.0, 2006-01-01
- - Moved all global/shared library state into a single object
- - Mutex objects are created through mutex factories instead of a global
- - Removed ::get_mutex(), ::initialize_mutex(), and Mutex::clone()
- - Removed the RNG_Quality enum entirely
- - There is now only a single global-use PRNG
- - Removed the no_aliases and no_oids options for LibraryInitializer
- - Removed the deprecated algorithms SEAL, ISAAC, and HAVAL
- - Change es_ftw to use unbuffered I/O
-
-* 1.4.11, 2005-12-31
- - Changed Whirlpool diffusion matrix to match updated algorithm spec
- - Fixed several engine module build errors introduced in 1.4.10
- - Fixed two build problems in es_capi; reported by Matthew Gregan
- - Added a constructor to DataSource_Memory taking a std::string
- - Placing the same Filter in multiple Pipes triggers an exception
- - The configure script accepts --docdir and --libdir
- - Merged doc/rngs.txt into the main API document
- - Thanks to Joel Low for several bug reports on early tarballs of 1.4.11
-
-* 1.4.10, 2005-12-18
- - Added an implementation of KASUMI, the block cipher used in 3G phones
- - Refactored Pipe; output queues are now managed by a distinct class
- - Made certain Filter facilities only available to subclasses of Fanout_Filter
- - There is no longer any overhead in Pipe for a message that has been read out
- - It is now possible to generate RSA keys as small as 128 bits
- - Changed some of the core classes to derive from Algorithm as a virtual base
- - Changed Randpool to use HMAC instead of a plain hash as the mixing function
- - Fixed a bug in the allocators; found and fixed by Matthew Gregan
- - Enabled the use of binary file I/O, when requested by the application
- - The OpenSSL engine's block cipher code was missing some deallocation calls
- - Disabled the es_ftw module on NetBSD, due to header problems there
- - Fixed a problem preventing tm_hard from building on MacOS X on PowerPC
- - Some cleanups for the modules that use inline assembler
- - config.h is now stored in build/ instead of build/include/botan/
- - The header util.h was split into bit_ops.h, parsing.h, and util.h
- - Cleaned up some redundant include directives
-
-* 1.4.9, 2005-11-06
- - Added the IBM-created AES candidate algorithm MARS
- - Added the South Korean block cipher SEED
- - Added the stream cipher Turing
- - Added the new hash function FORK-256
- - Deprecated the ISAAC stream cipher
- - Twofish and RC6 are significantly faster with GCC
- - Much better support for 64-bit PowerPC
- - Added support for high-resolution PowerPC timers
- - Fixed a bug in the configure script causing problems on FreeBSD
- - Changed ANSI X9.31 to support arbitrary block ciphers
- - Make the configure script a bit less noisy
- - Added more test vectors for some algorithms, including all the AES finalists
- - Various cosmetic source code cleanups
-
-* 1.4.8, 2005-10-16
- - Resolved a bad performance problem in the allocators; fix by Matt Johnston
- - Worked around a Visual Studio 2003 compilation problem introduced in 1.4.7
- - Renamed OMAC to CMAC to match the official NIST naming
- - Added single byte versions of update() to PK_Signer and PK_Verifier
- - Removed the unused reverse_bits and reverse_bytes functions
-
-* 1.4.7, 2005-09-25
- - Fixed major performance problems with recent versions of GNU C++
- - Added an implementation of the X9.31 PRNG
- - Removed the X9.17 and FIPS 186-2 PRNG algorithms
- - Changed defaults to use X9.31 PRNGs as global PRNG objects
- - Documentation updates to reflect the PRNG changes
- - Some cleanups related to the engine code
- - Removed two useless headers, base_eng.h and secalloc.h
- - Removed PK_Verifier::valid_signature
- - Fixed configure/build system bugs affecting MacOS X builds
- - Added support for the EKOPath x86-64 compiler
- - Added missing destructor for BlockCipherModePaddingMethod
- - Fix some build problems with Visual C++ 2005 beta
- - Fix some build problems with Visual C++ 2003 Workshop
-
-* 1.4.6, 2005-03-13
- - Fix an error in the shutdown code introduced in 1.4.5
- - Setting base/pkcs8_tries to 0 disables the builtin fail-out
- - Support for XMPP identifiers in X.509 certificates
- - Duplicate entries in X.509 DNs are removed
- - More fixes for Borland C++, from Friedemann Kleint
- - Add a workaround for buggy iostreams
-
-* 1.4.5, 2005-02-26
- - Add support for AES encryption of private keys
- - Minor fixes for PBES2 parameter decoding
- - Internal cleanups for global state variables
- - GCC 3.x version detection was broken in non-English locales
- - Work around a Sun Forte bug affecting mem_pool.h
- - Several fixes for Borland C++ 5.5, from Friedemann Kleint
- - Removed inclusion of init.h into base.h
- - Fixed a major bug in reading from certificate stores
- - Cleaned up a couple of mutex leaks
- - Removed some left-over debugging code
- - Removed SSL3_MAC, SSL3_PRF, and TLS_PRF
-
-* 1.4.4, 2004-12-02
- - Further tweaks to the pooling allocator
- - Modified EMSA3 to support SSL/TLS signatures
- - Changes to support Qt/QCA, from Justin Karneges
- - Moved mux_qt module code into mod_qt
- - Fixes for HP-UX from Mike Desjardins
-
-* 1.4.3, 2004-11-06
- - Split up SecureAllocator into Allocator and Pooling_Allocator
- - Memory locking allocators are more likely to be used
- - Fixed the placement of includes in some modules
- - Fixed broken installation procedure
- - Fixes in configure script to support alternate install programs
- - Modules can specify the minimum version they support
-
-* 1.4.2, 2004-10-31
- - Fixed a major CRL handling bug
- - Cipher and hash operations can be offloaded to engines
- - Added support for cipher and hash offload in OpenSSL engine
- - Improvements for 64-bit CPUs without a widening multiply instruction
- - Support for SHA2-* and Whirlpool with EMSA2
- - Fixed a long-standing build problem with conflicting include files
- - Fixed some examples that hadn't been updated for 1.4.x
- - Portability fixes for Solaris, *BSD, HP-UX, and others
- - Lots of fixes and cleanups in the configure script
- - Updated the Gentoo ebuild file
-
-* 1.4.1, 2004-10-10
- - Fixed major errors in the X.509 and PKCS #8 copy_key functions
- - Added a LAST_MESSAGE meta-message number for Pipe
- - Added new aliases (3DES and DES-EDE) for Triple-DES
- - Added some new functions to PK_Verifier
- - Cleaned up the KDF interface
- - Disabled tm_posix on *BSD due to header issues
- - Fixed a build problem on PowerPC with GNU C++ pre-3.4
-
-* 1.4.0, 2004-06-26
- - Added the FIPS 186 RNG back
- - Added copy_key functions for X.509 public keys and PKCS #8 private keys
- - Fixed PKCS #1 signatures with RIPEMD-128
- - Moved some code around to avoid warnings with Sun ONE compiler
- - Fixed a bug in botan-config affecting OpenBSD
- - Fixed some build problems on Tru64, HP-UX
- - Fixed compile problems with Intel C++, Compaq C++
-
-* 1.3.14, 2004-06-12
- - Added support for AEP's AEP1000/AEP2000 crypto cards
- - Added a Mutex module using Qt, from Justin Karneges
- - Added support for engine loading in LibraryInitializer
- - Tweaked SecureAllocator, giving 20% better performance under heavy load
- - Added timer and memory locking modules for Win32 (tm_win32, ml_win32)
- - Renamed PK_Engine to Engine_Core
- - Improved the Karatsuba cutoff points
- - Fixes for compiling with GCC 3.4 and Sun C++ 5.5
- - Fixes for Linux/s390, OpenBSD, and Solaris
- - Added support for Linux/s390x
- - The configure script was totally broken for 'generic' OS
- - Removed Montgomery reduction due to bugs
- - Removed an unused header, pkcs8alg.h
- - check --validate returns an error code if any tests failed
- - Removed duplicate entry in Unix command list for es_unix
- - Moved the Cert_Usage enumeration into X509_Store
- - Added new timing methods for PK benchmarks, clock_gettime and RDTSC
- - Fixed a few minor bugs in the configure script
- - Removed some deprecated functions from x509cert.h and pkcs10.h
- - Removed the 'minimal' module, has to be updated for Engine support
- - Changed MP_WORD_BITS macro to BOTAN_MP_WORD_BITS to clean up namespace
- - Documentation updates
-
-* 1.3.13, 2004-05-15
- - Major fixes for Cygwin builds
- - Minor MacOS X install fixes
- - The configure script is a little better at picking the right modules
- - Removed ml_unix from the 'unix' module set for Cygwin compatibility
- - Fixed a stupid compile problem in pkcs10.h
-
-* 1.3.12, 2004-05-02
- - Added ability to remove old entries from CRLs
- - Swapped the first two arguments of X509_CA::update_crl()
- - Added an < operator for MemoryRegion, so it can be used as a std::map key
- - Changed X.509 searching by DNS name from substring to full string compares
- - Renamed a few X509_Certificate and PKCS10_Request member functions
- - Fixed a problem when decoding some PKCS #10 requests
- - Hex_Decoder would not check inputs, reported by Vaclav Ovsik
- - Changed default CRL expire time from 30 days to 7 days
- - X509_CRL's default PEM header is now "X509 CRL", for OpenSSL compatibility
- - Corrected errors in the API doc, fixes from Ken Perano
- - More documentation about the Pipe/Filter code
-
-* 1.3.11, 2004-04-01
- - Fixed two show-stopping bugs in PKCS10_Request
- - Added some sanity checks in Pipe/Filter
- - The DNS and URI entries would get swapped in subjectAlternativeNames
- - MAC_Filter is now willing to not take a key at creation time
- - Setting the expiration times of certs and CRLs is more flexible
- - Fixed problems building on AIX with GCC
- - Fixed some problems in the tutorial pointed out by Dominik Vogt
- - Documentation updates
-
-* 1.3.10, 2004-03-27
- - Added support for OpenPGP's ASCII armor format
- - Cleaned up the RNG system; seeding is much more flexible
- - Added simple autoconfiguration abilities to configure.pl
- - Fixed a GCC 2.95.x compile problem
- - Updated the example configuration file
- - Documentation updates
-
-* 1.3.9, 2004-03-07
- - Added an engine using OpenSSL (requires 0.9.7 or later)
- - X509_Certificate would lose email addresses stored in the DN
- - Fixed a missing initialization in a BigInt constructor
- - Fixed several Visual C++ compile problems
- - Fixed some BeOS build problems
- - Fixed the WiderWake benchmark
-
-* 1.3.8, 2003-12-30
- - Internal changes to PK algorithms to divide data and algorithms
- - DSA/DH/NR/ElGamal constructors accept taking just the private key again
- - ElGamal keys now support being imported/exported as ASN.1 objects
- - Much more consistent and complete error checking in PK algorithms
- - Support for arbitrary backends (engines) for PK operations
- - Added Montgomery reductions
- - Added an engine that uses GNU MP (requires 4.1 or later)
- - Removed the obsolete mp_gmp module
- - Moved several initialization/shutdown functions to init.h
- - Major refactoring of the memory containers
- - New non-locking container, MemoryVector
- - Fixed 64-bit problems in BigInt::set_bit/clear_bit
- - Renamed PK_Key::check_params() to check_key()
- - Some incompatible changes to OctetString
- - Added version checking macros in version.h
- - Removed the fips140 module pending rewrite
- - Added some functions and hooks to help GUIs
- - Moved more shared code into MDx_HashFunction
- - Added a policy hook for specifying the encoding of X.509 strings
-
-* 1.3.7, 2003-12-12
- - Fixed a big security problem in es_unix
- - Fixed several stability problems in es_unix
- - Expanded the list of programs es_unix will try to use
- - SecureAllocator now only preallocates blocks in special cases
- - Added a special case in Global_RNG::seed for forcing a full poll
- - Removed the FIPS 186 RNG added in 1.3.5 pending further testing
- - Configure updates for PowerPC CPUs
- - Removed the (never tested) VAX support
- - Added support for S/390 Linux
-
-* 1.3.6, 2003-12-07
- - Added a new module 'minimal', which disables most algorithms
- - SecureAllocator allocates a few blocks at startup
- - A few minor MPI cleanups
- - RPM spec file cleanups and fixes
-
-* 1.3.5, 2003-11-30
- - Major improvements in ASN.1 string handling
- - Added partial support for ASN.1 UTF8 STRINGs and BMP STRINGs
- - Added partial support for the X.509v3 certificate policies extension
- - Centralized the handling of character set information
- - Added FIPS 140-2 startup self tests
- - Added a module (fips140) for doing extra FIPS 140-2 tests
- - Added FIPS 186-2 RNG
- - Improved ASN.1 BIT STRING handling
- - Removed a memory leak in PKCS10_Request
- - The encoding of DirectoryString now follows PKIX guidelines
- - Fixed some of the character set dependencies
- - Fixed a DER encoding error for tags greater than 30
- - The BER decoder can now handle tags larger than 30
- - Fixed tm_hard.cpp to recognize SPARC on more systems
- - Workarounds for a GCC 2.95.x bug in x509find.cpp
- - RPM changed to install into /usr instead of /usr/local
- - Added support for QNX
-
-* 1.2.8, 2003-11-21
- - Merged several important bug fixes from 1.3.x
-
-* 1.3.4, 2003-11-21
- - Added a module that does certain MPI operations using GNU MP
- - Added the X9.42 Diffie-Hellman PRF
- - The Zlib and Bzip2 objects now use custom allocators
- - Added member functions for directly hashing/MACing SecureVectors
- - Minor optimizations to the MPI addition and subtraction algorithms
- - Some cleanups in the low-level MPI code
- - Created separate AES-{128,192,256} objects
-
-* 1.3.3, 2003-11-17
- - The library can now be repeatedly initialized and shutdown without crashing
- - Fixed an off-by-one error in the CTS code
- - Fixed an error in the EMSA4 verification code
- - Fixed a memory leak in mutex.cpp (pointed out by James Widener)
- - Fixed a memory leak in Pthread_Mutex
- - Fixed several memory leaks in the testing code
- - Bulletproofed the EMSA/EME/KDF/MGF retrieval functions
- - Minor cleanups in SecureAllocator
- - Removed a needless mutex guarding the (stateless) global timer
- - Fixed a piece of bash-specific code in botan-config
- - X.509 objects report more information about decoding errors
- - Cleaned up some of the exception handling
- - Updated the example config file with new OIDSs
- - Moved the build instructions into a separate document, building.tex
-
-* 1.3.2, 2003-11-13
- - Fixed a bug preventing DSA signatures from verifying on X.509 objects
- - Made the X509_Store search routines more efficient and flexible
- - Added a function to X509_PublicKey to do easy public/private key matching
- - Added support for decoding indefinite length BER data
- - Changed Pipe's peek() to take an offset
- - Removed Filter::set_owns in favor of the new incr_owns function
- - Removed BigInt::zero() and BigInt::one()
- - Renamed the PEM related options from base/pem_* to pem/*
- - Added an option to specify the line width when encoding PEM
- - Removed the "rng/safe_longterm" option; it's always on now
- - Changed the cipher used for RNG super-encryption from ARC4 to WiderWake4+1
- - Cleaned up the base64/hex encoders and decoders
- - Added an ASN.1/BER decoder as an example
- - AES had its internals marked 'public' in previous versions
- - Changed the value of the ASN.1 NO_OBJECT enum
- - Various new hacks in the configure script
- - Removed the already nominal support for SunOS
-
-* 1.3.1, 2003-11-04
- - Generalized a few pieces of the DER encoder
- - PKCS8::load_key would fail if handed an unencrypted key
- - Added a failsafe so PKCS #8 key decoding can't go into an infinite loop
-
-* 1.3.0, 2003-11-02
- - Major redesign of the PKCS #8 private key import/export system
- - Added a small amount of UI interface code for getting passphrases
- - Added heuristics that tell if a key, cert, etc is stored as PEM or BER
- - Removed CS-Cipher, SHARK, ThreeWay, MD5-MAC, and EMAC
- - Removed certain deprecated constructors of RSA, DSA, DH, RW, NR
- - Made PEM decoding more forgiving of extra text before the header
-
-* 1.2.7, 2003-10-31
- - Added support for reading configuration files
- - Added constructors so NR and RW keys can be imported easily
- - Fixed mp_asm64, which was completely broken in 1.2.6
- - Removed tm_hw_ia32 module; replaced by tm_hard
- - Added support for loading certain oddly formed RSA certificates
- - Fixed spelling of NON_REPUDIATION enum
- - Renamed the option default_to_ca to v1_assume_ca
- - Fixed a minor bug in X.509 certificate generation
- - Fixed a latent bug in the OID lookup code
- - Updated the RPM spec file
- - Added to the tutorial
-
-* 1.2.6, 2003-07-04
- - Major performance increase for PK algorithms on most 64-bit systems
- - Cleanups in the low-level MPI code to support asm implementations
- - Fixed build problems with some versions of Compaq's C++ compiler
- - Removed useless constructors for NR public and private keys
- - Removed support for the patch_file directive in module files
- - Removed several deprecated functions
-
-* 1.2.5, 2003-06-22
- - Fixed a tricky and long-standing memory leak in Pipe
- - Major cleanups and fixes in the memory allocation system
- - Removed alloc_mlock, which has been superseded by the ml_unix module
- - Removed a denial of service vulnerability in X509_Store
- - Fixed compilation problems with VS .NET 2003 and Codewarrior 8
- - Added another variant of PKCS8::load_key, taking a memory buffer
- - Fixed various minor/obscure bugs which occurred when MP_WORD_BITS != 32
- - BigInt::operator%=(word) was a no-op if the input was a power of 2
- - Fixed portability problems in BigInt::to_u32bit
- - Fixed major bugs in SSL3-MAC
- - Cleaned up some messes in the PK algorithms
- - Cleanups and extensions for OMAC and EAX
- - Made changes to the entropy estimation function
- - Added a 'beos' module set for use on BeOS
- - Officially deprecated a few X509:: and PKCS8:: functions
- - Moved the contents of primes.h to numthry.h
- - Moved the contents of x509opt.h to x509self.h
- - Removed the (empty) desx.h header
- - Documentation updates
-
-* 1.2.4, 2003-05-29
- - Fixed a bug in EMSA1 affecting NR signature verification
- - Fixed a few latent bugs in BigInt related to word size
- - Removed an unused function, mp_add2_nc, from the MPI implementation
- - Reorganized the core MPI files
-
-* 1.2.3, 2003-05-20
- - Fixed a bug that prevented DSA/NR key generation
- - Fixed a bug that prevented importing some root CA certs
- - Fixed a bug in the BER decoder when handing optional bit or byte strings
- - Fixed the encoding of authorityKeyIdentifier in X509_CA
- - Added a sanity check in PBKDF2 for zero length passphrases
- - Added versions of X509::load_key and PKCS8::load_key that take a file name
- - X509_CA generates 128 bit serial numbers now
- - Added tests to check PK key generation
- - Added a simplistic X.509 CA example
- - Cleaned up some of the examples
-
-* 1.2.2, 2003-05-13
- - Add checks to prevent any BigInt bugs from revealing an RSA or RW key
- - Changed the interface of Global_RNG::seed
- - Major improvements for the es_unix module
- - Added another Win32 entropy source, es_win32
- - The Win32 CryptoAPI entropy source can now poll multiple providers
- - Improved the BeOS entropy source
- - Renamed pipe_unixfd module to fd_unix
- - Fixed a file descriptor leak in the EGD module
- - Fixed a few locking bugs
-
-* 1.2.1, 2003-05-06
- - Added ANSI X9.23 compatible CBC padding
- - Added an entropy source using Win32 CryptoAPI
- - Removed the Pipe I/O operators taking a FILE*
- - Moved the BigInt encoding/decoding functions into the BigInt class
- - Integrated several fixes for VC++ 7 (from Hany Greiss)
- - Fixed the configure.pl script for Windows builds
-
-* 1.2.0, 2003-04-28
- - Tweaked the Karatsuba cut-off points
- - Increased the allowed keylength of HMAC and Blowfish
- - Removed the 'mpi_ia32' module, pending rewrite
- - Workaround a GCC 2.95.x bug in eme1.cpp
-
-* 1.1.13, 2003-04-22
- - Added OMAC
- - Added EAX authenticated cipher mode
- - Diffie-Hellman would not do blinding in some cases
- - Optimized the OFB and CTR modes
- - Corrected Skipjack's word ordering, as per NIST clarification
- - Support for all subject/issuer attribute types required by RFC 3280
- - The removeFromCRL CRL reason code is now handled correctly
- - Increased the flexibility of the allocators
- - Renamed Rijndael to AES, created aes.h, deleted rijndael.h
- - Removed support for the 'no_timer' LibraryInitializer option
- - Removed 'es_pthr' module, pending further testing
- - Cleaned up get_ciph.cpp
-
-* 1.1.12, 2003-04-15
- - Fixed a ASN.1 string encoding bug
- - Fixed a pair of X509_DN encoding problems
- - Base64_Decoder and Hex_Decoder can now validate input
- - Removed support for the LibraryInitializer option 'egd_path'
- - Added tests for DSA X.509 and PKCS #8 key formats
- - Removed a long deprecated feature of DH_PrivateKey's constructor
- - Updated the RPM .spec file
- - Major documentation updates
-
-* 1.1.11, 2003-04-07
- - Added PKCS #10 certificate requests
- - Changed X509_Store searching interface to be more flexible
- - Added a generic Certificate_Store interface
- - Added a function for generating self-signed X.509 certs
- - Cleanups and changes to X509_CA
- - New examples for PKCS #10 and self-signed certificates
- - Some documentation updates
-
-* 1.1.10, 2003-04-03
- - X509_CA can now generate new X.509 CRLs
- - Added blinding for RSA, RW, DH, and ElGamal to prevent timing attacks
- - More certificate and CRL extensions/attributes are supported
- - Better DN handling in X.509 certificates/CRLs
- - Added a DataSink hierarchy (suggested by Jim Darby)
- - Consolidated SecureAllocator and ManagedAllocator
- - Many cleanups and generalizations
- - Added a (slow) pthreads based EntropySource
- - Fixed some threading bugs
-
-* 1.1.9, 2003-02-25
- - Added support for using X.509v2 CRLs
- - Fixed several bugs in the path validation algorithm
- - Certificates can be verified for a particular usage
- - Algorithm for comparing distinguished names now follows X.509
- - Cleaned up the code for the es_beos, es_ftw, es_unix modules
- - Documentation updates
-
-* 1.1.8, 2003-01-29
- - Fixes for the certificate path validation algorithm in X509_Store
- - Fixed a bug affecting X509_Certificate::is_ca_cert()
- - Added a general configuration interface for policy issues
- - Cleanups and API changes in the X.509 CA, cert, and store code
- - Made various options available for X509_CA users
- - Changed X509_Time's interface to work around time_t problems
- - Fixed a theoretical weakness in Randpool's entropy mixing function
- - Fixed problems compiling with GCC 2.95.3 and GCC 2.96
- - Fixed a configure bug (reported by Jon Wilson) affecting MinGW
-
-* 1.1.7, 2003-01-12
- - Fixed an obscure but dangerous bug in SecureVector::swap
- - Consolidated SHA-384 and SHA-512 to save code space
- - Added SSL3-MAC and SSL3-PRF
- - Documentation updates, including a new tutorial
-
-* 1.0.2, 2003-01-12
- - Fixed an obscure SEGFAULT causing bug in Pipe
- - Fixed an obscure but dangerous bug in SecureVector::swap
-
-* 1.1.6, 2002-12-10
- - Initial support for X.509v3 certificates and CAs
- - Major redesign/rewrite of the ASN.1 encoding/decoding code
- - Added handling for DSA/NR signatures encoded as DER SEQUENCEs
- - Documented the generic cipher lookup interface
- - Added an (untested) entropy source for BeOS
- - Various cleanups and bug fixes
-
-* 1.1.5, 2002-11-17
- - Added the discrete logarithm integrated encryption system (DLIES)
- - Various optimizations for BigInt
- - Added support for assembler optimizations in modules
- - Added BigInt x86 optimizations module (mpi_ia32)
-
-* 1.1.4, 2002-11-10
- - Speedup of 15-30% for PK algorithms
- - Implemented the PBES2 encryption scheme
- - Fixed a potential bug in decoding RSA and RW private keys
- - Changed the DL_Group class interface to handle different formats better
- - Added support for PKCS #3 encoded DH parameters
- - X9.42 DH parameters use a PEM label of 'X942 DH PARAMETERS'
- - Added key pair consistency checking
- - Fixed a compatibility problem with gcc 2.96 (pointed out by Hany Greiss)
- - A botan-config script is generated at configure time
- - Documentation updates
-
-* 1.1.3, 2002-11-03
- - Added a generic public/private key loading interface
- - Fixed a small encoding bug in RSA, RW, and DH
- - Changed the PK encryption/decryption interface classes
- - ECB supports using padding methods
- - Added a function-based interface for library initialization
- - Added support for RIPEMD-128 and Tiger PKCS#1 v1.5 signatures
- - The cipher mode benchmarks now use 128-bit AES instead of DES
- - Removed some obsolete typedefs
- - Removed OpenCL support (opencl.h, the OPENCL_* macros, etc)
- - Added tests for PKCS #8 encoding/decoding
- - Added more tests for ECB and CBC
-
-* 1.1.2, 2002-10-21
- - Support for PKCS #8 encoded RSA, DSA, and DH private keys
- - Support for Diffie-Hellman X.509 public keys
- - Major reorganization of how X.509 keys are handled
- - Added PKCS #5 v2.0's PBES1 encryption scheme
- - Added a generic cipher lookup interface
- - Added the WiderWake4+1 stream cipher
- - Added support for sync-able stream ciphers
- - Added a 'paranoia level' option for the LibraryInitializer
- - More security for RNG output meant for long term keys
- - Added documentation for some of the new 1.1.x features
- - CFB's feedback argument is now specified in bits
- - Renamed CTR class to CTR_BE
- - Updated the RSA and DSA examples to use X.509 and PKCS #8 key formats
-
-* 1.1.1, 2002-10-15
- - Added the Korean hash function HAS-160
- - Partial support for RSA and DSA X.509 public keys
- - Added a mostly functional BER encoder/decoder
- - Added support for non-deterministic MAC functions
- - Initial support for PEM encoding/decoding
- - Internal cleanups in the PK algorithms
- - Several new convenience functions in Pipe
- - Fixed two nasty bugs in Pipe
- - Messed with the entropy sources for es_unix
- - Discrete logarithm groups are checked for safety more closely now
- - For compatibility with GnuPG, ElGamal now supports DSA-style groups
-
-* 1.1.0, 2002-09-14
- - Added entropy estimation to the RNGs
- - Improved the overall design of both Randpool and ANSI_X917_RNG
- - Added a separate RNG for nonce generation
- - Added window exponentiation support in power_mod
- - Added a get_s2k function and the PKCS #5 S2K algorithms
- - Added the TLSv1 PRF
- - Replaced BlockCipherModeIV typedef with InitializationVector class
- - Renamed PK_Key_Agreement_Scheme to PK_Key_Agreement
- - Renamed SHA1 -> SHA_160 and SHA2_x -> SHA_x
- - Added support for RIPEMD-160 PKCS#1 v1.5 signatures
- - Changed the key agreement scheme interface
- - Changed the S2K and KDF interfaces
- - Better SCAN compatibility for HAVAL, Tiger, MISTY1, SEAL, RC5, SAFER-SK
- - Added support for variable-pass Tiger
- - Major speedup for Rabin-Williams key generation
-
-* 1.0.1, 2002-09-14
- - Fixed a minor bug in Randpool::random()
- - Added some new aliases and typedefs for 1.1.x compatibility
- - The 4096-bit RSA benchmark key was decimal instead of hex
- - EMAC was returning an incorrect name
-
-* 1.0.0, 2002-08-26
- - Octal I/O of BigInt is now supported
- - Fixed portability problems in the es_egd module
- - Generalized IV handling in the block cipher modes
- - Added Karatsuba multiplication and k-ary exponentiation
- - Fixed a problem in the multiplication routines
-
-* 0.9.2, 2002-08-18
- - DH_PrivateKey::public_value() was returning the wrong value
- - Various BigInt optimizations
- - The filters.h header now includes hex.h and base64.h
- - Moved Counter mode to ctr.h
- - Fixed a couple minor problems with VC++ 7
- - Fixed problems with the RPM spec file
-
-* 0.9.1, 2002-08-10
- - Grand rename from OpenCL to Botan
- - Major optimizations for the PK algorithms
- - Added ElGamal encryption
- - Added Whirlpool
- - Tweaked memory allocation parameters
- - Improved the method of seeding the global RNG
- - Moved pkcs1.h to eme_pkcs.h
- - Added more test vectors for some algorithms
- - Fixed error reporting in the BigInt tests
- - Removed Default_Timer, it was pointless
- - Added some new example applications
- - Removed some old examples that weren't that interesting
- - Documented the compression modules
-
-* 0.9.0, 2002-08-03
- - EMSA4 supports variable salt size
- - PK_* can take a string naming the encoding method to use
- - Started writing some internals documentation
-
-* 0.8.7, 2002-07-30
- - Fixed bugs in EME1 and EMSA4
- - Fixed a potential crash at shutdown
- - Cipher modes returned an ill-formed name
- - Removed various deprecated types and headers
- - Cleaned up the Pipe interface a bit
- - Minor additions to the documentation
- - First stab at a Visual C++ makefile (doc/Makefile.vc7)
-
-* 0.8.6, 2002-07-25
- - Added EMSA4 (aka PSS)
- - Brought the manual up to date; many corrections and additions
- - Added a parallel hash function construction
- - Lookup supports all available algorithms now
- - Lazy initialization of the lookup tables
- - Made more discrete logarithm groups available through get_dl_group()
- - StreamCipher_Filter supports seeking (if the underlying cipher does)
- - Minor optimization for GCD calculations
- - Renamed SAFER_SK128 to SAFER_SK
- - Removed many previously deprecated functions
- - Some now-obsolete functions, headers, and types have been deprecated
- - Fixed some bugs in DSA prime generation
- - DL_Group had a constructor for DSA-style prime gen but it wasn't defined
- - Reversed the ordering of the two arguments to SEAL's constructor
- - Fixed a threading problem in the PK algorithms
- - Fixed a minor memory leak in lookup.cpp
- - Fixed pk_types.h (it was broken in 0.8.5)
- - Made validation tests more verbose
- - Updated the check and example applications
-
-* 0.8.5, 2002-07-21
- - Major changes to constructors for DL-based cryptosystems (DSA, NR, DH)
- - Added a DL_Group class
- - Reworking of the pubkey internals
- - Support in lookup for aliases and PK algorithms
- - Renamed CAST5 to CAST_128 and CAST256 to CAST_256
- - Added EMSA1
- - Reorganization of header files
- - LibraryInitializer will install new allocator types if requested
- - Fixed a bug in Diffie-Hellman key generation
- - Did a workaround in pipe.cpp for GCC 2.95.x on Linux
- - Removed some debugging code from init.cpp that made FTW ES useless
- - Better checking for invalid arguments in the PK algorithms
- - Reduced Base64 and Hex default line length (if line breaking is used)
- - Fixes for HP's aCC compiler
- - Cleanups in BigInt
-
-* 0.8.4, 2002-07-14
- - Added Nyberg-Rueppel signatures
- - Added Diffie-Hellman key exchange (kex interface is subject to change)
- - Added KDF2
- - Enhancements to the lookup API
- - Many things formerly taking pointers to algorithms now take names
- - Speedups for prime generation
- - LibraryInitializer has support for seeding the global RNG
- - Reduced SAFER-SK128 memory consumption
- - Reversed the ordering of public and private key values in DSA constructor
- - Fixed serious bugs in MemoryMapping_Allocator
- - Fixed memory leak in Lion
- - FTW_EntropySource was not closing the files it read
- - Fixed line breaking problem in Hex_Encoder
-
-* 0.8.3, 2002-06-09
- - Added DSA and Rabin-Williams signature schemes
- - Added EMSA3
- - Added PKCS#1 v1.5 encryption padding
- - Added Filters for PK algorithms
- - Added a Keyed_Filter class
- - LibraryInitializer processes arguments now
- - Major revamp of the PK interface classes
- - Changed almost all of the Filters for non-template operation
- - Changed HMAC, Lion, Luby-Rackoff to non-template classes
- - Some fairly minor BigInt optimizations
- - Added simple benchmarking for PK algorithms
- - Added hooks for fixed base and fixed exponent modular exponentiation
- - Added some examples for using RSA
- - Numerous bugfixes and cleanups
- - Documentation updates
-
-* 0.8.2, 2002-05-18
- - Added an (experimental) algorithm lookup interface
- - Added code for directly testing BigInt
- - Added SHA2-384
- - Optimized SHA2-512
- - Major optimization for Adler32 (thanks to Dan Nicolaescu)
- - Various minor optimizations in BigInt and related areas
- - Fixed two bugs in X9.19 MAC, both reported by Darren Starsmore
- - Fixed a bug in BufferingFilter
- - Made a few fixes for MacOS X
- - Added a workaround in configure.pl for GCC 2.95.x
- - Better support for PowerPC, ARM, and Alpha
- - Some more cleanups
-
-* 0.8.1, 2002-05-06
- - Major code cleanup (check doc/deprecated.txt)
- - Various bugs fixed, including several portability problems
- - Renamed MessageAuthCode to MessageAuthenticationCode
- - A replacement for X917 is in x917_rng.h
- - Changed EMAC to non-template class
- - Added ANSI X9.19 compatible CBC-MAC
- - TripleDES now supports 128 bit keys
-
-* 0.8.0, 2002-04-24
- - Merged BigInt: many bugfixes and optimizations since alpha2
- - Added RSA (rsa.h)
- - Added EMSA2 (emsa2.h)
- - Lots of new interface code for public key algorithms (pk_base.h, pubkey.h)
- - Changed some interfaces, including SymmetricKey, to support the global rng
- - Fixed a serious bug in ManagedAllocator
- - Renamed RIPEMD128 to RIPEMD_128 and RIPEMD160 to RIPEMD_160
- - Removed some deprecated stuff
- - Added a global random number generator (rng.h)
- - Added clone functions to most of the basic algorithms
- - Added a library initializer class (init.h)
- - Version macros in version.h
- - Moved the base classes from opencl.h to base.h
- - Renamed the bzip2 module to comp_bzip2 and zlib to comp_zlib
- - Documentation updates for the new stuff (still incomplete)
- - Many new deprecated things: check doc/deprecated.txt
-
-* 0.7.10, 2002-04-07
- - Added EGD_EntropySource module (es_egd)
- - Added a file tree walking EntropySource (es_ftw)
- - Added MemoryLocking_Allocator module (alloc_mlock)
- - Renamed the pthr_mux, unix_rnd, and mmap_mem modules
- - Changed timer mechanism; the clock method can be switched on the fly.
- - Renamed MmapDisk_Allocator to MemoryMapping_Allocator
- - Renamed ent_file.h to es_file.h (ent_file.h is around, but deprecated)
- - Fixed several bugs in MemoryMapping_Allocator
- - Added more default sources for Unix_EntropySource
- - Changed SecureBuffer to use same allocation methods as SecureVector
- - Added bigint_divcore into mp_core to support BigInt alpha2 release
- - Removed some Pipe functions deprecated since 0.7.8
- - Some fixes for the configure program
-
-* 0.7.9, 2002-03-19
- - Memory allocation substantially revamped
- - Added memory allocation method based on mmap(2) in the mmap_mem module
- - Added ECB and CTS block cipher modes (ecb.h, cts.h)
- - Added a Mutex interface (mutex.h)
- - Added module pthr_mux, implementing the Mutex interface
- - Added Threaded Filter interface (thr_filt.h)
- - All algorithms can now by keyed with SymmetricKey objects
- - More testing occurs with --validate (expected failures)
- - Fixed two bugs reported by Hany Greiss, in Luby-Rackoff and RC6
- - Fixed a buffering bug in Bzip_Decompress and Zlib_Decompress
- - Made X917 safer (and about 1/3 as fast)
- - Documentation updates
-
-* 0.7.8, 2002-02-28
- - More capabilities for Pipe, inspired by SysV STREAMS, including peeking,
-   better buffering, and stack ops. NOT BACKWARDS COMPATIBLE: SEE DOCUMENTATION
- - Added a BufferingFilter class
- - Added popen() based EntropySource for generic Unix systems (unix_rnd)
- - Moved 'devrand' module into main distribution (ent_file.h), renamed to
-   File_EntropySource, and changed interface somewhat.
- - Made Randpool somewhat more conservative and also 25% faster
- - Minor fixes and updates for the configure script
- - Added some tweaks for memory allocation
- - Documentation updates for the new Pipe interface
- - Fixed various minor bugs
- - Added a couple of new example programs (stack and hasher2)
-
-* 0.7.7, 2001-11-24
- - Filter::send now works in the constructor of a Filter subclass
- - You may now have to include <opencl/pipe.h> explicitly in some code
- - Added preliminary PK infrastructure classes in pubkey.h and pkbase.h
- - Enhancements to SecureVector (append, destroy functions)
- - New infrastructure for secure memory allocation
- - Added IEEE P1363 primitives MGF1, EME1, KDF1
- - Rijndael optimizations and cleanups
- - Changed CipherMode<B> to BlockCipherMode(B*)
- - Fixed a nasty bug in pipe_unixfd
- - Added portions of the BigInt code into the main library
- - Support for VAX, SH, POWER, PowerPC-64, Intel C++
-
-* 0.7.6, 2001-10-14
- - Fixed several serious bugs in SecureVector created in 0.7.5
- - Square optimizations
- - Fixed shared objects on MacOS X and HP-UX
- - Fixed static libs for KCC 4.0; works with KCC 3.4g as well
- - Full support for Athlon and K6 processors using GCC
- - Added a table of prime numbers < 2**16 (primes.h)
- - Some minor documentation updates
-
-* 0.7.5, 2001-08-19
- - Split checksum.h into adler32.h, crc24.h, and crc32.h
- - Split modes.h into cbc.h, cfb.h, and ofb.h
- - CBC_wPadding* has been replaced by CBC_Encryption and CBC_Decryption
- - Added OneAndZeros and NoPadding methods for CBC
- - Added Lion, a very fast block cipher construction
- - Added an S2K base class (s2k.h) and an OpenPGP_S2K class (pgp_s2k.h)
- - Basic types (ciphers, hashes, etc) know their names now (call name())
- - Changed the EntropySource type somewhat
- - Big speed-ups for ISAAC, Adler32, CRC24, and CRC32
- - Optimized CAST-256, DES, SAFER-SK, Serpent, SEAL, MD2, and RIPEMD-160
- - Some semantics of SecureVector have changed slightly
- - The mlock module has been removed for the time being
- - Added string handling functions for hashes and MACs
- - Various non-user-visible cleanups
- - Shared library soname is now set to the full version number
-
-* 0.7.4, 2001-07-15
- - New modules: Zlib, gettimeofday and x86 RTC timers, Unix I/O for Pipe
- - Fixed a vast number of errors in the config script/makefile/specfile
- - Pipe now has a stdio(3) interface as well as C++ iostreams
- - ARC4 supports skipping the first N bytes of the cipher stream (ala MARK4)
- - Bzip2 supports decompressing multiple concatenated streams, and flushing
- - Added a simple 'overall average' score to the benchmarks
- - Fixed a small bug in the POSIX timer module
- - Removed a very-unlikely-to-occur bug in most of the hash functions
- - filtbase.h now includes <iosfwd>, not <iostream>
- - Minor documentation updates
-
-* 0.7.3, 2001-06-08
- - Fix build problems on Solaris/SPARC
- - Fix build problems with Perl versions < 5.6
- - Fixed some stupid code that broke on a few compilers
- - Added string handling functions to Pipe
- - MISTY1 optimizations
-
-* 0.7.2, 2001-06-03
- - Build system supports modules
- - Added modules for mlock, a /dev/random EntropySource, POSIX1.b timers
- - Added Bzip2 compression filter, contributed by Peter Jones
- - GNU make no longer required (tested with 4.4BSD pmake and Solaris make)
- - Fixed minor bug in several of the hash functions
- - Various other minor fixes and changes
- - Updates to the documentation
-
-* 0.7.1, 2001-05-16
- - Rewrote configure script: more consistent and complete
- - Made it easier to find out parameters of types at run time (opencl.h)
- - New functions for finding the version being used (version.h)
- - New SymmetricKey interface for Filters (symkey.h)
- - InvalidKeyLength now records what the invalid key length was
- - Optimized DES, CS-Cipher, MISTY1, Skipjack, XTEA
- - Changed GOST to use correct S-box ordering (incompatible change)
- - Benchmark code was almost totally rewritten
- - Many more entries in the test vector file
- - Fixed minor and idiotic bug in check.cpp
-
-* 0.7.0, 2001-03-01
- - First public release
+Release Notes
+========================================
+
+2011
+----------------------------------------
+
+1.9.16-dev, ????-??-??
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Second release candidate for 1.10.0
+  * The documenation, previously written in LaTeX, is now in
+    reStructuredText suitable for processing by Sphinx, which can
+    generate HTML, PDFs, or man pages.
+  * Disable the by-default 'strong' checking of private keys that are
+    loaded from storage. You can always request key material sanity
+    checking using check_key.
+  * Bring back removed functions min_keylength_of, max_keylength_of,
+    keylength_multiple_of in lookup.h to avoid breaking applications.
+
+1.9.15, 2011-03-21
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * First release candidate for 1.10.0
+  * Modify how message expansion is done in SHA-256 and SHA-512.
+    Instead of expanding the entire message at the start, compute them
+    in the minimum number of registers. Values are computed 15 rounds
+    before they are needed. On a Core i7-860, GCC 4.5.2, went from
+    143 to 157 MiB/s in SHA-256, and 211 to 256 MiB/s in SHA-512.
+  * Pipe will delete empty output queues as soon as they are no longer
+    needed, even if earlier messages still have data unread. However an
+    (empty) entry in a deque of pointers will remain until all prior
+    messages are completely emptied.
+  * Avoid reading the SPARC %tick register on OpenBSD as unlike Linux
+    the kernel will not trap and emulate it for us, causing a illegal
+    instruction crash.
+  * Improve detection and autoconfiguration for ARM processors.
+
+1.9.14, 2011-03-01
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+   * Add support for bcrypt, OpenBSD's password hashing scheme
+   * Add support for NIST's AES key wrapping algorithm
+   * Fix an infinite loop in zlib filters introduced in 1.9.11 (PR 142)
+
+1.9.13, 2011-02-19
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Update Keccak to the round 3 variant
+  * Fix ordering in GOST 34.10 signatures to match DNSSEC specifications
+  * Use size_t instead of u32bit for small integers in DER/BER codecs
+  * Add new build option --distribution-info
+  * Fix problems in the amalgamation build
+  * Fix building under Clang 2.9 and Sun Studio 12
+
+2010
+----------------------------------------
+
+1.9.12, 2010-12-13
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add the Keccak hash function
+  * Fix compilation problems in Python wrappers
+  * Fix compilation problem in OpenSSL engine
+  * Update SQLite3 database encryption codec
+
+1.9.11, 2010-11-29
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Many SSL/TLS APIs have changed. This API is still unstable.
+  * The SSL interface requires TR1 (uses std::tr1::function)
+  * Fix SSL handshake failures when using RC4 ciphersuites
+  * Fix a number of CRL encoding and decoding bugs
+  * Counter mode now always encrypts 256 blocks in parallel
+  * Code where u32bit was used to represent a length now uses size_t
+  * Use small tables in the first round of AES
+  * Removed AES class: app must choose AES-128, AES-192, or AES-256
+  * Add hex encoding/decoding functions that can be used without a Pipe
+  * Add base64 encoding functions that can be used without a Pipe
+  * Add to_string function to X509_Certificate
+  * Add support for dynamic engine loading on Windows
+  * Replace BlockCipher::BLOCK_SIZE attribute with function block_size()
+  * Replace HashFunction::HASH_BLOCK_SIZE attribute with hash_block_size()
+  * Changed semantics of MemoryRegion::resize and clear to match STL
+  * Removed MemoryRegion::append, replaced by push_back and operator+=
+  * Move PBKDF lookup to engine system
+  * The IDEA key schedule has been changed to run in constant time
+  * Avoid a possible timing vulnerability in Montgomery reduction
+  * Add Algorithm and Key_Length_Specification classes
+  * Switch default PKCS #8 encryption algorithm from AES-128 to AES-256
+  * Update Skein-512 to match the v1.3 specification
+  * Allow using PBKDF2 with empty passphrases
+  * Add compile-time deprecation warnings for GCC, Clang, and MSVC
+  * Support use of HMAC(SHA-256) and CMAC(Blowfish) in passhash9
+  * Improve support for Intel Atom processors
+  * Fix compilation problems under Sun Studio and Clang
+
+1.8.11, 2010-11-02
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix a number of CRL encoding and decoding bugs
+  * When building a debug library under VC++, use the debug runtime
+  * Fix compilation under Sun Studio on Linux and Solaris
+  * Add several functions for compatability with 1.9
+  * In the examples, read most input files as binary
+  * The Perl build script has been removed in this release
+
+1.8.10, 2010-08-31
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Switch default PKCS #8 encryption algorithm from 3DES to AES-256
+  * Increase default hash iterations from 2048 to 10000 in PBES1 and PBES2
+  * Use small tables in the first round of AES
+  * Add PBKDF typedef and get_pbkdf for better compatability with 1.9
+  * Add version of S2K::derive_key taking salt and iteration count
+  * Enable the /proc-walking entropy source on NetBSD
+  * Fix the doxygen makefile target
+
+1.9.10, 2010-08-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add a constant time AES implementation using SSSE3
+  * Add support for loading new Engines at runtime
+  * Use GCC byteswap intrinsics where possible
+  * Drop support for building with Python 2.4
+  * Fix benchmarking of block ciphers in ECB mode
+  * Consolidate the two x86 assembly engines
+  * Rename S2K to PBKDF
+
+1.9.9, 2010-06-28
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add new X509::BER_encode and PKCS8::BER_encode
+  * Give all Filter objects a name() function
+  * Add Keyed_Filter::valid_iv_length
+  * Increase default iteration counts for private key encryption
+  * Fix compilation of mp_asm64 on 64-bit MIPS with GCC 4.4 and later
+  * Fix compilation under Apple's GCC 4.2
+  * Expand and update the Doxygen documentation
+
+1.8.9, 2010-06-16
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Use constant time multiplication in IDEA
+  * Avoid possible timing attack against OAEP decoding
+  * Add new X509::BER_encode and PKCS8::BER_encode
+  * Enable DLL builds under Windows
+  * Add Win32 installer support
+  * Add support for the Clang compiler
+  * Fix problem in semcem.h preventing build under Clang or GCC 3.4
+  * Fix bug that prevented creation of DSA groups under 1024 bits
+  * Fix crash in GMP_Engine if library is shutdown and reinitialized
+  * Work around problem with recent binutils in x86-64 SHA-1
+  * The Perl build script is no longer supported and refuses to run by default
+
+1.9.8, 2010-06-14
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add support for wide multiplications on 64-bit Windows
+  * Use constant time multiplication in IDEA
+  * Avoid possible timing attack against OAEP decoding
+  * Removed FORK-256; rarely used and it has been broken
+  * Rename --use-boost-python to --with-boost-python
+  * Skip building shared libraries on MinGW/Cygwin
+  * Fix creation of 512 and 768 bit DL groups using the DSA kosherizer
+  * Fix compilation on GCC versions before 4.3 (missing cpuid.h)
+  * Fix compilation under the Clang compiler
+
+1.9.7, 2010-04-27
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * TLS: Support reading SSLv2 client hellos
+  * TLS: Add support for SEED ciphersuites (RFC 4162)
+  * Add Comb4P hash combiner function
+  * Fix checking of EMSA_Raw signatures with leading 0 bytes
+
+1.9.6, 2010-04-09
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * TLS: Add support for TLS v1.1
+  * TLS: Support server name indicator extension
+  * TLS: Fix server handshake
+  * TLS: Fix server using DSA certificates
+  * TLS: Avoid timing channel between CBC padding check and MAC verification
+
+1.9.5, 2010-03-29
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Numerous ECC optimizations
+  * Fix GOST 34.10-2001 X.509 key loading
+  * Allow PK_Signer's fault protection checks to be toggled off
+  * Avoid using pool-based locking allocator if we can't mlock
+  * Remove all runtime options
+  * New BER_Decoder::{decode_and_check, decode_octet_string_bigint}
+  * Remove SecureBuffer in favor of SecureVector length parameter
+  * HMAC_RNG: Perform a poll along with user-supplied entropy
+  * Fix crash in MemoryRegion if Allocator::get failed
+  * Fix small compilation problem on FreeBSD
+
+1.9.4, 2010-03-09
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add the Ajisai SSLv3/TLSv1.0 implementation
+  * Add GOST 34.10-2001 public key signature scheme
+  * Add SIMD implementation of Noekeon
+  * Add SSE2 implementation of IDEA
+  * Extend Salsa20 to support longer IVs (XSalsa20)
+  * Perform XTS encryption and decryption in parallel where possible
+  * Perform CBC decryption in parallel where possible
+  * Add SQLite3 db encryption codec, contributed by Olivier de Gaalon
+  * Add a block cipher cascade construction
+  * Add support for password hashing for authentication (passhash9.h)
+  * Add support for Win32 high resolution system timers
+  * Major refactoring and API changes in the public key code
+  * Use consistency checking (anti-fault attack) for all signature schemes
+  * Changed S2K interface: derive_key now takes salt, iteration count
+  * Remove dependency on TR1 for ECC and CVC code
+  * Renamed ECKAEG to its more usual name, ECDH
+  * Fix crash in GMP_Engine if library is shutdown and reinitialized
+  * Fix an invalid memory read in MD4
+  * Fix Visual C++ static builds
+  * Remove Timer class entirely
+  * Switch default PKCS #8 encryption algorithm from 3DES to AES-128
+  * New option --gen-amalgamation for creating a SQLite-style amalgamation
+  * Many headers are now explicitly internal-use-only and are not installed
+  * Greatly improve the Win32 installer
+  * Several fixes for Visual C++ debug builds
+
+2009
+----------------------------------------
+
+1.9.3, 2009-11-19
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add new AES implementation using Intel's AES instruction intrinsics
+  * Add an implementation of format preserving encryption
+  * Allow use of any hash function in X.509 certificate creation
+  * Optimizations for MARS, Skipjack, and AES
+  * Set macros for available SIMD instructions in build.h
+  * Add support for using InnoSetup to package Windows builds
+  * By default build a DLL on Windows
+
+1.9.2, 2009-11-03
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add SIMD version of XTEA
+  * Support both SSE2 and AltiVec SIMD for Serpent and XTEA
+  * Optimizations for SHA-1 and SHA-2
+  * Add AltiVec runtime detection
+  * Fix x86 CPU identification with Intel C++ and Visual C++
+
+1.8.8, 2009-11-03
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Alter Skein-512 to match the tweaked 1.2 specification
+  * Fix use of inline asm for access to x86 bswap function
+  * Allow building the library without AES enabled
+  * Add 'powerpc64' alias to ppc64 arch for Gentoo ebuild
+
+1.9.1, 2009-10-23
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Better support for Python and Perl wrappers
+  * Add an implementation of Blue Midnight Wish (Round 2 tweak version)
+  * Modify Skein-512 to match the tweaked 1.2 specification
+  * Add threshold secret sharing (draft-mcgrew-tss-02)
+  * Add runtime cpu feature detection for x86/x86-64
+  * Add code for general runtime self testing for hashes, MACs, and ciphers
+  * Optimize XTEA; twice as fast as before on Core2 and Opteron
+  * Convert CTR_BE and OFB from filters to stream ciphers
+  * New parsing code for SCAN algorithm names
+  * Enable SSE2 optimizations under Visual C++
+  * Remove all use of C++ exception specifications
+  * Add support for GNU/Hurd and Clang/LLVM
+
+1.9.0, 2009-09-09
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add support for parallel invocation of block ciphers where possible
+  * Add SSE2 implementation of Serpent
+  * Add Rivest's package transform (an all or nothing transform)
+  * Minor speedups to the Turing key schedule
+  * Fix processing multiple messages in XTS mode
+  * Add --no-autoload option to configure.py, for minimized builds
+  * The previously used configure.pl script is no longer supported
+
+1.8.7, 2009-09-09
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix processing multiple messages in XTS mode
+  * Add --no-autoload option to configure.py, for minimized builds
+
+1.8.6, 2009-08-13
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add Cryptobox, a set of simple password-based encryption routines
+  * Only read world-readable files when walking /proc for entropy
+  * Fix building with TR1 disabled
+  * Fix x86 bswap support for Visual C++
+  * Fixes for compilation under Sun C++
+  * Add support for Dragonfly BSD (contributed by Patrick Georgi)
+  * Add support for the Open64 C++ compiler
+  * Build fixes for MIPS systems running Linux
+  * Minor changes to license, now equivalent to the FreeBSD/NetBSD license
+
+1.8.5, 2009-07-23
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Change configure.py to work on stock Python 2.4
+  * Avoid a crash in Skein_512::add_data processing a zero-length input
+  * Small build fixes for SPARC, ARM, and HP-PA processors
+  * The test suite now returns an error code from main() if any tests failed
+
+1.8.4, 2009-07-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix a bug in nonce generation in the Miller-Rabin test
+
+1.8.3, 2009-07-11
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add a new Python configuration script
+  * Add the Skein-512 SHA-3 candidate hash function
+  * Add the XTS block cipher mode from IEEE P1619
+  * Fix random_prime when generating a prime of less than 7 bits
+  * Improve handling of low-entropy situations during PRNG seeding
+  * Change random device polling to prefer /dev/urandom over /dev/random
+  * Use an input insensitive implementation of same_mem instead of memcmp
+  * Correct DataSource::discard_next to return the number of discarded bytes
+  * Provide a default value for AutoSeeded_RNG::reseed
+  * Fix Gentoo bug 272242
+
+1.8.2, 2009-04-07
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Make entropy polling more flexible and in most cases faster
+  * GOST 28147 now supports multiple sbox parameters
+  * Added the GOST 34.11 hash function
+  * Fix botan-config problems on MacOS X
+
+1.8.1, 2009-01-20
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Avoid a valgrind warning in es_unix.cpp on 32-bit Linux
+  * Fix memory leak in PKCS8 load_key and encrypt_key
+  * Relicense api.tex from CC-By-SA 2.5 to BSD
+  * Fix botan-config on MacOS X, Solaris
+
+2008
+----------------------------------------
+
+1.8.0, 2008-12-08
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix compilation on Solaris with GCC
+
+1.7.24, 2008-12-01
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix a compatibility problem with SHA-512/EMSA3 signature padding
+  * Fix bug preventing EGD/PRNGD entropy poller from working
+  * Fix integer overflow in Pooling_Allocator::get_more_core (bug id #27)
+  * Add EMSA3_Raw, a variant of EMSA3 called CKM_RSA_PKCS in PKCS #11
+  * Add support for SHA-224 in EMSA2 and EMSA3 PK signature padding schemes
+  * Add many more test vectors for RSA with EMSA2, EMSA3, and EMSA4
+  * Wrap private structs in SSE2 SHA-1 code in anonymous namespace
+  * Change configure.pl's CPU autodetection output to be more consistent
+  * Disable using OpenSSL's AES due to crashes of unknown cause
+  * Fix warning in /proc walking entropy poller
+  * Fix compilation with IBM XLC for Cell 0.9-200709
+
+1.7.23, 2008-11-23
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Change to use TR1 (thus enabling ECDSA) with GCC and ICC
+  * Optimize almost all hash functions, especially MD4 and Tiger
+  * Add configure.pl options --{with,without}-{bzip2,zlib,openssl,gnump}
+  * Change Timer to be pure virtual, and add ANSI_Clock_Timer
+  * Cache socket descriptors in the EGD entropy source
+  * Avoid bogging down startup in /proc walking entropy source
+  * Remove Buffered_EntropySource helper class
+  * Add a Default_Benchmark_Timer typedef in benchmark.h
+  * Add examples using benchmark.h and Algorithm_Factory
+  * Add ECC tests from InSiTo
+  * Minor documentation updates
+
+1.7.22, 2008-11-17
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add provider preferences to Algorithm_Factory
+  * Fix memory leaks in PBE_PKCS5v20 and get_pbe introduced in 1.7.21
+  * Optimize AES encryption and decryption (about 10% faster)
+  * Enable SSE2 optimized SHA-1 implementation on Intel Prescott CPUs
+  * Fix nanoseconds overflow in benchmark code
+  * Remove Engine::add_engine
+
+1.7.21, 2008-11-11
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Make algorithm lookup much more configuable
+  * Add facilities for runtime performance testing of algorithms
+  * Drop use of entropy estimation in the PRNGs
+  * Increase intervals between HMAC_RNG automatic reseeding
+  * Drop InitializerOptions class, all options but thread safety
+
+1.7.20, 2008-11-09
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Namespace pkg-config file by major and minor versions
+  * Cache device descriptors in Device_EntropySource
+  * Split base.h into {block_cipher,stream_cipher,mac,hash}.h
+  * Removed get_mgf function from lookup.h
+
+1.7.19, 2008-11-06
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add HMAC_RNG, based on a design by Hugo Krawczyk
+  * Optimized the Turing stream cipher (about 20% faster on x86-64)
+  * Modify Randpool's reseeding algorithm to poll more sources
+  * Add a new AutoSeeded_RNG in auto_rng.h
+  * OpenPGP_S2K changed to take hash object instead of name
+  * Add automatic identification for Intel's Prescott processors
+
+1.7.18, 2008-10-22
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add Doxygen comments from InSiTo
+  * Add ECDSA and ECKAEG benchmarks
+  * Add configure.pl switch --with-tr1-implementation
+  * Fix configure.pl's --with-endian and --with-unaligned-mem options
+  * Added support for pkg-config
+  * Optimize byteswap with x86 inline asm for Visual C++ by Yves Jerschow
+  * Use const references to avoid copying overhead in CurveGFp, GFpModulus
+
+1.7.17, 2008-10-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add missing ECDSA object identifiers
+  * Fix error in x86 and x86-64 assembler affecting GF(p) math
+  * Remove Boost dependency from GF(p) math
+  * Modify botan-config to not print -L/usr/lib or -L/usr/local/lib
+  * Add BOTAN_DLL macro to over 30 classes missing it
+  * Rename the two SHA-2 base classes for consistency
+
+1.7.16, 2008-10-09
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add several missing pieces needed for ECDSA and ECKAEG
+  * Add Card Verifiable Certificates from InSiTo
+  * Add SHA-224 from InSiTo
+  * Add BSI variant of EMSA1 from InSiTo
+  * Add GF(p) and ECDSA tests from InSiTo
+  * Split ECDSA and ECKAEG into distinct modules
+  * Allow OpenSSL and GNU MP engines to be built with public key algos disabled
+  * Rename sha256.h to sha2_32.h and sha_64.h to sha2_64.h
+
+1.7.15, 2008-10-07
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add GF(p) arithmetic from InSiTo
+  * Add ECDSA and ECKAEG implementations from InSiTo
+  * Minimize internal dependencies, allowing for smaller build configurations
+  * Add new User Manual and Architecture Guide from FlexSecure GmbH
+  * Alter configure.pl options for better autotools compatibility
+  * Update build instructions for recent changes to configure.pl
+  * Fix CPU detection using /proc/cpuinfo
+
+1.7.14, 2008-09-30
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Split library into parts allowing modular builds
+  * Add (very preliminary) CMS support to the main library
+  * Some constructors now require object pointers instead of names
+  * Support multiple implementations of the same algorithm
+  * Build support for Pentium-M processors, from Derek Scherger
+  * Build support for MinGW/MSYS, from Zbigniew Zagorski
+  * Use inline assembly for bswap on 32-bit x86
+
+1.7.13, 2008-09-27
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add SSLv3 MAC, SSLv3 PRF, and TLS v1.0 PRF from Ajisai
+  * Allow all examples to compile even if compression not enabled
+  * Make CMAC's polynomial doubling operation a public class method
+  * Use the -m64 flag when compiling with Sun Forte on x86-64
+  * Clean up and slightly optimize CMAC::final_result
+
+1.7.12, 2008-09-18
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add x86 assembly for Visual Studio C++, by Luca Piccarreta
+  * Add a Perl XS module, by Vaclav Ovsik
+  * Add SWIG-based wrapper for Botan
+  * Add SSE2 implementation of SHA-1, by Dean Gaudet
+  * Remove the BigInt::sig_words cache due to bugs
+  * Combined the 4 Blowfish sboxes, suggested by Yves Jerschow
+  * Changed BigInt::grow_by and BigInt::grow_to to be non-const
+  * Add private assignment operators to classes that don't support assignment
+  * Benchmark RSA encryption and signatures
+  * Added test programs for random_prime and ressol
+  * Add high resolution timers for IA-64, HP-PA, S390x
+  * Reduce use of the RNG during benchmarks
+  * Fix builds on STI Cell PPU
+  * Add support for IBM's XLC compiler
+  * Add IETF 8192 bit MODP group
+
+1.7.11, 2008-09-11
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added the Salsa20 stream cipher
+  * Optimized Montgomery reduction, Karatsuba squaring
+  * Added 16x16->32 word Comba multiplication and squaring
+  * Use a much larger Karatsuba cutoff point
+  * Remove bigint_mul_add_words
+  * Inlined several BigInt functions
+  * Add useful information to the generated build.h
+  * Rename alg_{ia32,amd64} modules to asm_{ia32,amd64}
+  * Fix the Windows build
+
+1.7.10, 2008-09-05
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Public key benchmarks run using a selection of random keys
+  * New benchmark timer options are clock_gettime, gettimeofday, times, clock
+  * Including reinterpret_cast optimization for xor_buf in default header
+  * Split byte swapping and word rotation functions into distinct headers
+  * Add IETF modp 6144 group and 2048 and 3072 bit DSS groups
+  * Optimizes BigInt right shift
+  * Add aliases in DL_Group::Format enum
+  * BigInt now caches the significant word count
+
+1.7.9, 2008-08-27
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Make clear() in most algorithm base classes a pure virtual
+  * Add noexec stack marker for GNU linker in assembly code
+  * Avoid string operations in ressol
+  * Compilation fixes for MinGW and Visual Studio C++ 2008
+  * Some autoconfiguration fixes for Windows
+
+1.6.5, 2008-08-27
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add noexec stack marker for GNU linker in assembly code
+  * Fix autoconfiguration problem on x86 with GCC 4.2 and 4.3
+
+1.7.8, 2008-07-15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added the block cipher Noekeon
+  * Remove global deref_alias function
+  * X509_Store takes timeout options as constructor arguments
+  * Add Shanks-Tonelli algorithm, contributed by FlexSecure GmbH
+  * Extend random_prime() for generating primes of any bit length
+  * Remove Config class
+  * Allow adding new entropy via base RNG interface
+  * Reseeding a X9.31 PRNG also reseeds the underlying PRNG
+
+1.7.7, 2008-06-28
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Remove the global PRNG object
+  * The PK filter objects were removed
+  * Add a test suite for the ANSI X9.31 PRNG
+  * Much cleaner and (mostly) thread-safe reimplementation of es_ftw
+  * Remove both default arguments to ANSI_X931_RNG's constructor
+  * Remove the randomizing version of OctetString::change
+  * Make the cipher and MAC to use in Randpool configurable
+  * Move RandomNumberGenerator declaration to rng.h
+  * RSA_PrivateKey will not generate keys smaller than 1024 bits
+  * Fix an error decoding BER UNIVERSAL types with special taggings
+
+1.7.6, 2008-05-05
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Initial support for Windows DLLs, from Joel Low
+  * Reset the position pointer when a new block is generated in X9.32 PRNG
+  * Timer objects are now treated as entropy sources
+  * Moved several ASN.1-related enums from enums.h to an appropriate header
+  * Removed the AEP module, due to inability to test
+  * Removed Global_RNG and rng.h
+  * Removed system_clock
+  * Removed Library_State::UI and the pulse callback logic
+
+1.7.5, 2008-04-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * The API of X509_CA::sign_request was altered to avoid race conditions
+  * New type Pipe::message_id to represent the Pipe message number
+  * Remove the Named_Mutex_Holder for a small performance gain
+  * Removed several unused or rarely used functions from Config
+  * Ignore spaces inside of a decimal string in BigInt::decode
+  * Allow using a std::istream to initialize a DataSource_Stream object
+  * Fix compilation problem in zlib compression module
+  * The chunk sized used by Pooling_Allocator is now a compile time setting
+  * The size of random blinding factors is now a compile time setting
+  * The install target no longer tries to set a particular owner/group
+
+1.7.4, 2008-03-10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Use unaligned memory read/writes on systems that allow it, for performance
+  * Assembly for x86-64 for accessing the bswap instruction
+  * Use larger buffers in ARC4 and WiderWAKE for significant throughput increase
+  * Unroll loops in SHA-160 for a few percent increase in performance
+  * Fix compilation with GCC 3.2 in es_ftw and es_unix
+  * Build fix for NetBSD systems
+  * Prevent es_dev from being built except on Unix systems
+
+1.6.4, 2008-03-08
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix a compilation problem with Visual Studio C++ 2003
+
+1.7.3, 2008-01-23
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * New invocation syntax for configure.pl with several new options
+  * Support for IPv4 addresses in a subject alternative name
+  * New fast poll for the generic Unix entropy source (es_unix)
+  * The es_file entropy source has been replaced by the es_dev module
+  * The malloc allocator does not inherit from Pooling_Allocator anymore
+  * The path that es_unix will search in are now fully user-configurable
+  * Truncate X9.42 PRF output rather than allow counter overflow
+  * PowerPC is now assumed to be big-endian
+
+2007
+----------------------------------------
+
+1.7.2, 2007-10-13
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Initialize the global library state lazily
+  * Add plain CBC-MAC for backwards compatibility with old systems
+  * Clean up some of the self test code
+  * Throw a sensible exception if a DL_Group is not found
+  * Truncate KDF2 output rather than allowing counter overflow
+  * Add newly assigned OIDs for SHA-2 and DSA with SHA-224/256
+  * Fix a Visual Studio compilation problem in x509stat.cpp
+
+1.7.1, 2007-07-23
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix a race condition in the algorithm object cache
+  * HMAC key schedule optimization
+  * The build header sets a macro defining endianness, if known
+  * New word load/store abstraction allowing further optimization
+  * Modify most of the library to avoid use the C-style casts
+  * Use higher resolution timers in symmetric benchmarks
+
+1.6.3, 2007-07-23
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix a race condition in the algorithm lookup cache
+  * Fix problems building the memory pool on some versions of Visual C++
+
+1.7.0, 2007-05-19
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * DSA parameter generation now follows FIPS 186-3
+  * Added OIDs for Rabin-Williams and Nyberg-Rueppel
+  * Somewhat better support for out of tree builds
+  * Minor optimizations for RC2 and Tiger
+  * Documentation updates
+  * Update the todo list
+
+1.6.2, 2007-03-24
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix autodection on Athlon64s running Linux
+  * Fix builds on QNX and compilers using STLport
+  * Remove a call to abort() that crept into production
+
+1.6.1, 2007-01-20
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix some base64 decoder bugs
+  * Add a new option to base64 encoding, to always append a newline
+  * Fix some build problems under Visual Studio with debug enabled
+  * Fix a bug in BER_Decoder that was triggered under some compilers
+
+2006
+----------------------------------------
+
+1.6.0, 2006-12-17
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Minor cleanups versus 1.5.13
+
+1.5.13, 2006-12-10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Compilation fixes for the bzip2, zlib, and GNU MP modules
+  * Better support for Intel C++ and EKOpath C++ on x86-64
+
+1.5.12, 2006-10-27
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Cleanups in the initialization routines
+  * Add some x86-64 assembly for multiply-add
+  * Fix problems generating very small (below 384 bit) RSA keys
+  * Support out of tree builds
+  * Bring some of the documentation up to date
+  * More improvements to the Python bindings
+
+1.5.11, 2006-09-10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Removed the Algorithm base class
+  * Various cleanups in the public key inheritance hierarchy
+  * Major overhaul of the configure/build setup
+  * Added x86 assembler implementations of Serpent and low-level MPI code
+  * Optimizations for the SHA-1 x86 assembler
+  * Various improvements to the Python wrappers
+  * Work around a Visual Studio compiler bug
+
+1.5.10, 2006-08-13
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add x86 assembler versions of MD4, MD5, and SHA-1
+  * Expand InitializerOptions' language to support on/off switches
+  * Fix definition of OID 2.5.4.8; was accidentally changed in 1.5.9
+  * Fix possible resource leaks in the mmap allocator
+  * Slightly optimized buffering in MDx_HashFunction
+  * Initialization failures are dealt with somewhat better
+  * Add an example implementing Pollard's Rho algorithm
+  * Better option handling in the test/benchmark tool
+  * Expand the xor_ciph example to support longer keys
+  * Some updates to the documentation
+
+1.5.9, 2006-07-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed bitrot in the AEP engine
+  * Fix support for marking certificate/CRL extensions as critical
+  * Significant cleanups in the library state / initialization code
+  * LibraryInitializer takes an explicit InitializerOptions object
+  * Make Mutex_Factory an abstract class, add Default_Mutex_Factory
+  * Change configuration access to using global_state()
+  * Add support for global named mutexes throughout the library
+  * Add some STL wrappers for the delete operator
+  * Change how certificates are created to be more flexible and general
+
+1.5.8, 2006-06-23
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Many internal cleanups to the X.509 cert/CRL code
+  * Allow for application code to support new X.509 extensions
+  * Change the return type of X509_Certificate::{subject,issuer}_info
+  * Allow for alternate character set handling mechanisms
+  * Fix a bug that was slowing squaring performance somewhat
+  * Fix a very hard to hit overflow bug in the C version of word3_muladd
+  * Minor cleanups to the assembler modules
+  * Disable es_unix module on FreeBSD due to build problem on FreeBSD 6.1
+  * Support for GCC 2.95.x has been dropped in this release
+
+1.5.7, 2006-05-28
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Further, major changes to the BER/DER coding system
+  * Updated the Qt mutex module to use Mutex_Factory
+  * Moved the library global state object into an anonymous namespace
+  * Drop the Visual C++ x86 assembly module due to bugs
+
+1.5.6, 2006-03-01
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * The low-level DER/BER coding system was redesigned and rewritten
+  * Portions of the certificate code were cleaned up internally
+  * Use macros to substantially clean up the GCC assembly code
+  * Added 32-bit x86 assembly for Visual C++ (by Luca Piccarreta)
+  * Avoid a couple of spurious warnings under Visual C++
+  * Some slight cleanups in X509_PublicKey::key_id
+
+1.5.5, 2006-02-04
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a potential infinite loop in the memory pool code (Matt Johnston)
+  * Made Pooling_Allocator::Memory_Block an actual class of sorts
+  * Some small optimizations to the division and modulo computations
+  * Cleaned up the implementation of some of the BigInt operators
+  * Reduced use of dynamic memory allocation in low-level BigInt functions
+  * A few simplifications in the Randpool mixing function
+  * Removed power(), as it was not particularly useful (or fast)
+  * Fixed some annoying bugs in the benchmark code
+  * Added a real credits file
+
+1.5.4, 2006-01-29
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Integrated x86 and amd64 assembly code, contributed by Luca Piccarreta
+  * Fixed a memory access off-by-one in the Karatsuba code
+  * Changed Pooling_Allocator's free list search to a log(N) algorithm
+  * Merged ModularReducer with its only subclass, Barrett_Reducer
+  * Fixed sign-handling bugs in some of the division and modulo code
+  * Renamed the module description files to modinfo.txt
+  * Further cleanups in the initialization code
+  * Removed BigInt::add and BigInt::sub
+  * Merged all the division-related functions into just divide()
+  * Modified the <mp_asmi.h> functions to allow for better optimizations
+  * Made the number of bits polled from an EntropySource user configurable
+  * Avoid including <algorithm> in <botan/secmem.h>
+  * Fixed some build problems with Sun Forte
+  * Removed some dead code from bigint_modop
+  * Fix the definition of same_mem
+
+1.5.3, 2006-01-24
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Many optimizations in the low-level multiple precision integer code
+  * Added hooks for assembly implementations of the MPI code
+  * Support for the X.509 issuer alternative name extension in new certs
+  * Fixed a bug in the decompression modules; found and patched by Matt Johnston
+  * New Windows mutex module (mux_win32), by Luca Piccarreta
+  * Changed the Windows timer module to use QueryPerformanceCounter
+  * mem_pool.cpp was using std::set iterators instead of std::multiset ones
+  * Fixed a bug in X509_CA preventing users from disabling particular extensions
+  * Fixed the mp_asm64 module, which was entirely broken in 1.5.2
+  * Fixed some module build problems on FreeBSD and Tru64
+
+1.5.2, 2006-01-15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed an off-by-one memory read in MISTY1::key()
+  * Fixed a nasty memory leak in Output_Buffers::retire()
+  * Reimplemented the memory allocator from scratch
+  * Improved memory caching in Montgomery exponentiation
+  * Optimizations for multiple precision addition and subtraction
+  * Fixed a build problem in the hardware timer module on 64-bit PowerPC
+  * Changed default Karatsuba cutoff to 12 words (was 14)
+  * Removed MemoryRegion::bits(), which was unused and incorrect
+  * Changed maximum HMAC keylength to 1024 bits
+  * Various minor Makefile and build system changes
+  * Avoid using std::min in <secmem.h> to bypass Windows libc macro pollution
+  * Switched checks/clock.cpp back to using clock() by default
+  * Enabled the symmetric algorithm tests, which were accidentally off in 1.5.1
+  * Removed the Default_Mutex's unused clone() member function
+
+1.4.12, 2006-01-15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed an off-by-one memory read in MISTY1::key()
+  * Fixed a nasty memory leak in Output_Buffers::retire()
+  * Changed maximum HMAC keylength to 1024 bits
+  * Fixed a build problem in the hardware timer module on 64-bit PowerPC
+
+1.5.1, 2006-01-08
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Implemented Montgomery exponentiation
+  * Implemented generalized Karatsuba multiplication and squaring
+  * Implemented Comba squaring for 4, 6, and 8 word inputs
+  * Added new Modular_Exponentiator and Power_Mod classes
+  * Removed FixedBase_Exp and FixedExponent_Exp
+  * Fixed a performance regression in get_allocator introduced in 1.5.0
+  * Engines can now offer S2K algorithms and block cipher padding methods
+  * Merged the remaining global 'algolist' code into Default_Engine
+  * The low-level MPI code is linked as C again
+  * Replaced BigInt's get_nibble with the more general get_substring
+  * Some documentation updates
+
+1.5.0, 2006-01-01
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Moved all global/shared library state into a single object
+  * Mutex objects are created through mutex factories instead of a global
+  * Removed ::get_mutex(), ::initialize_mutex(), and Mutex::clone()
+  * Removed the RNG_Quality enum entirely
+  * There is now only a single global-use PRNG
+  * Removed the no_aliases and no_oids options for LibraryInitializer
+  * Removed the deprecated algorithms SEAL, ISAAC, and HAVAL
+  * Change es_ftw to use unbuffered I/O
+
+2005
+----------------------------------------
+
+1.4.11, 2005-12-31
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Changed Whirlpool diffusion matrix to match updated algorithm spec
+  * Fixed several engine module build errors introduced in 1.4.10
+  * Fixed two build problems in es_capi; reported by Matthew Gregan
+  * Added a constructor to DataSource_Memory taking a std::string
+  * Placing the same Filter in multiple Pipes triggers an exception
+  * The configure script accepts --docdir and --libdir
+  * Merged doc/rngs.txt into the main API document
+  * Thanks to Joel Low for several bug reports on early tarballs of 1.4.11
+
+1.4.10, 2005-12-18
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added an implementation of KASUMI, the block cipher used in 3G phones
+  * Refactored Pipe; output queues are now managed by a distinct class
+  * Made certain Filter facilities only available to subclasses of Fanout_Filter
+  * There is no longer any overhead in Pipe for a message that has been read out
+  * It is now possible to generate RSA keys as small as 128 bits
+  * Changed some of the core classes to derive from Algorithm as a virtual base
+  * Changed Randpool to use HMAC instead of a plain hash as the mixing function
+  * Fixed a bug in the allocators; found and fixed by Matthew Gregan
+  * Enabled the use of binary file I/O, when requested by the application
+  * The OpenSSL engine's block cipher code was missing some deallocation calls
+  * Disabled the es_ftw module on NetBSD, due to header problems there
+  * Fixed a problem preventing tm_hard from building on MacOS X on PowerPC
+  * Some cleanups for the modules that use inline assembler
+  * config.h is now stored in build/ instead of build/include/botan/
+  * The header util.h was split into bit_ops.h, parsing.h, and util.h
+  * Cleaned up some redundant include directives
+
+1.4.9, 2005-11-06
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added the IBM-created AES candidate algorithm MARS
+  * Added the South Korean block cipher SEED
+  * Added the stream cipher Turing
+  * Added the new hash function FORK-256
+  * Deprecated the ISAAC stream cipher
+  * Twofish and RC6 are significantly faster with GCC
+  * Much better support for 64-bit PowerPC
+  * Added support for high-resolution PowerPC timers
+  * Fixed a bug in the configure script causing problems on FreeBSD
+  * Changed ANSI X9.31 to support arbitrary block ciphers
+  * Make the configure script a bit less noisy
+  * Added more test vectors for some algorithms, including all the AES finalists
+  * Various cosmetic source code cleanups
+
+1.4.8, 2005-10-16
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Resolved a bad performance problem in the allocators; fix by Matt Johnston
+  * Worked around a Visual Studio 2003 compilation problem introduced in 1.4.7
+  * Renamed OMAC to CMAC to match the official NIST naming
+  * Added single byte versions of update() to PK_Signer and PK_Verifier
+  * Removed the unused reverse_bits and reverse_bytes functions
+
+1.4.7, 2005-09-25
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed major performance problems with recent versions of GNU C++
+  * Added an implementation of the X9.31 PRNG
+  * Removed the X9.17 and FIPS 186-2 PRNG algorithms
+  * Changed defaults to use X9.31 PRNGs as global PRNG objects
+  * Documentation updates to reflect the PRNG changes
+  * Some cleanups related to the engine code
+  * Removed two useless headers, base_eng.h and secalloc.h
+  * Removed PK_Verifier::valid_signature
+  * Fixed configure/build system bugs affecting MacOS X builds
+  * Added support for the EKOPath x86-64 compiler
+  * Added missing destructor for BlockCipherModePaddingMethod
+  * Fix some build problems with Visual C++ 2005 beta
+  * Fix some build problems with Visual C++ 2003 Workshop
+
+1.4.6, 2005-03-13
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix an error in the shutdown code introduced in 1.4.5
+  * Setting base/pkcs8_tries to 0 disables the builtin fail-out
+  * Support for XMPP identifiers in X.509 certificates
+  * Duplicate entries in X.509 DNs are removed
+  * More fixes for Borland C++, from Friedemann Kleint
+  * Add a workaround for buggy iostreams
+
+1.4.5, 2005-02-26
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add support for AES encryption of private keys
+  * Minor fixes for PBES2 parameter decoding
+  * Internal cleanups for global state variables
+  * GCC 3.x version detection was broken in non-English locales
+  * Work around a Sun Forte bug affecting mem_pool.h
+  * Several fixes for Borland C++ 5.5, from Friedemann Kleint
+  * Removed inclusion of init.h into base.h
+  * Fixed a major bug in reading from certificate stores
+  * Cleaned up a couple of mutex leaks
+  * Removed some left-over debugging code
+  * Removed SSL3_MAC, SSL3_PRF, and TLS_PRF
+
+2004
+----------------------------------------
+
+1.4.4, 2004-12-02
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Further tweaks to the pooling allocator
+  * Modified EMSA3 to support SSL/TLS signatures
+  * Changes to support Qt/QCA, from Justin Karneges
+  * Moved mux_qt module code into mod_qt
+  * Fixes for HP-UX from Mike Desjardins
+
+1.4.3, 2004-11-06
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Split up SecureAllocator into Allocator and Pooling_Allocator
+  * Memory locking allocators are more likely to be used
+  * Fixed the placement of includes in some modules
+  * Fixed broken installation procedure
+  * Fixes in configure script to support alternate install programs
+  * Modules can specify the minimum version they support
+
+1.4.2, 2004-10-31
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a major CRL handling bug
+  * Cipher and hash operations can be offloaded to engines
+  * Added support for cipher and hash offload in OpenSSL engine
+  * Improvements for 64-bit CPUs without a widening multiply instruction
+  * Support for SHA2-* and Whirlpool with EMSA2
+  * Fixed a long-standing build problem with conflicting include files
+  * Fixed some examples that hadn't been updated for 1.4.x
+  * Portability fixes for Solaris, BSD, HP-UX, and others
+  * Lots of fixes and cleanups in the configure script
+  * Updated the Gentoo ebuild file
+
+1.4.1, 2004-10-10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed major errors in the X.509 and PKCS #8 copy_key functions
+  * Added a LAST_MESSAGE meta-message number for Pipe
+  * Added new aliases (3DES and DES-EDE) for Triple-DES
+  * Added some new functions to PK_Verifier
+  * Cleaned up the KDF interface
+  * Disabled tm_posix on BSD due to header issues
+  * Fixed a build problem on PowerPC with GNU C++ pre-3.4
+
+1.4.0, 2004-06-26
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added the FIPS 186 RNG back
+  * Added copy_key functions for X.509 public keys and PKCS #8 private keys
+  * Fixed PKCS #1 signatures with RIPEMD-128
+  * Moved some code around to avoid warnings with Sun ONE compiler
+  * Fixed a bug in botan-config affecting OpenBSD
+  * Fixed some build problems on Tru64, HP-UX
+  * Fixed compile problems with Intel C++, Compaq C++
+
+1.3.14, 2004-06-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added support for AEP's AEP1000/AEP2000 crypto cards
+  * Added a Mutex module using Qt, from Justin Karneges
+  * Added support for engine loading in LibraryInitializer
+  * Tweaked SecureAllocator, giving 20% better performance under heavy load
+  * Added timer and memory locking modules for Win32 (tm_win32, ml_win32)
+  * Renamed PK_Engine to Engine_Core
+  * Improved the Karatsuba cutoff points
+  * Fixes for compiling with GCC 3.4 and Sun C++ 5.5
+  * Fixes for Linux/s390, OpenBSD, and Solaris
+  * Added support for Linux/s390x
+  * The configure script was totally broken for 'generic' OS
+  * Removed Montgomery reduction due to bugs
+  * Removed an unused header, pkcs8alg.h
+  * check --validate returns an error code if any tests failed
+  * Removed duplicate entry in Unix command list for es_unix
+  * Moved the Cert_Usage enumeration into X509_Store
+  * Added new timing methods for PK benchmarks, clock_gettime and RDTSC
+  * Fixed a few minor bugs in the configure script
+  * Removed some deprecated functions from x509cert.h and pkcs10.h
+  * Removed the 'minimal' module, has to be updated for Engine support
+  * Changed MP_WORD_BITS macro to BOTAN_MP_WORD_BITS to clean up namespace
+  * Documentation updates
+
+1.3.13, 2004-05-15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Major fixes for Cygwin builds
+  * Minor MacOS X install fixes
+  * The configure script is a little better at picking the right modules
+  * Removed ml_unix from the 'unix' module set for Cygwin compatibility
+  * Fixed a stupid compile problem in pkcs10.h
+
+1.3.12, 2004-05-02
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added ability to remove old entries from CRLs
+  * Swapped the first two arguments of X509_CA::update_crl()
+  * Added an < operator for MemoryRegion, so it can be used as a std::map key
+  * Changed X.509 searching by DNS name from substring to full string compares
+  * Renamed a few X509_Certificate and PKCS10_Request member functions
+  * Fixed a problem when decoding some PKCS #10 requests
+  * Hex_Decoder would not check inputs, reported by Vaclav Ovsik
+  * Changed default CRL expire time from 30 days to 7 days
+  * X509_CRL's default PEM header is now "X509 CRL", for OpenSSL compatibility
+  * Corrected errors in the API doc, fixes from Ken Perano
+  * More documentation about the Pipe/Filter code
+
+1.3.11, 2004-04-01
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed two show-stopping bugs in PKCS10_Request
+  * Added some sanity checks in Pipe/Filter
+  * The DNS and URI entries would get swapped in subjectAlternativeNames
+  * MAC_Filter is now willing to not take a key at creation time
+  * Setting the expiration times of certs and CRLs is more flexible
+  * Fixed problems building on AIX with GCC
+  * Fixed some problems in the tutorial pointed out by Dominik Vogt
+  * Documentation updates
+
+1.3.10, 2004-03-27
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added support for OpenPGP's ASCII armor format
+  * Cleaned up the RNG system; seeding is much more flexible
+  * Added simple autoconfiguration abilities to configure.pl
+  * Fixed a GCC 2.95.x compile problem
+  * Updated the example configuration file
+  * Documentation updates
+
+1.3.9, 2004-03-07
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added an engine using OpenSSL (requires 0.9.7 or later)
+  * X509_Certificate would lose email addresses stored in the DN
+  * Fixed a missing initialization in a BigInt constructor
+  * Fixed several Visual C++ compile problems
+  * Fixed some BeOS build problems
+  * Fixed the WiderWake benchmark
+
+2003
+----------------------------------------
+
+1.3.8, 2003-12-30
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Internal changes to PK algorithms to divide data and algorithms
+  * DSA/DH/NR/ElGamal constructors accept taking just the private key again
+  * ElGamal keys now support being imported/exported as ASN.1 objects
+  * Much more consistent and complete error checking in PK algorithms
+  * Support for arbitrary backends (engines) for PK operations
+  * Added Montgomery reductions
+  * Added an engine that uses GNU MP (requires 4.1 or later)
+  * Removed the obsolete mp_gmp module
+  * Moved several initialization/shutdown functions to init.h
+  * Major refactoring of the memory containers
+  * New non-locking container, MemoryVector
+  * Fixed 64-bit problems in BigInt::set_bit/clear_bit
+  * Renamed PK_Key::check_params() to check_key()
+  * Some incompatible changes to OctetString
+  * Added version checking macros in version.h
+  * Removed the fips140 module pending rewrite
+  * Added some functions and hooks to help GUIs
+  * Moved more shared code into MDx_HashFunction
+  * Added a policy hook for specifying the encoding of X.509 strings
+
+1.3.7, 2003-12-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a big security problem in es_unix
+  * Fixed several stability problems in es_unix
+  * Expanded the list of programs es_unix will try to use
+  * SecureAllocator now only preallocates blocks in special cases
+  * Added a special case in Global_RNG::seed for forcing a full poll
+  * Removed the FIPS 186 RNG added in 1.3.5 pending further testing
+  * Configure updates for PowerPC CPUs
+  * Removed the (never tested) VAX support
+  * Added support for S/390 Linux
+
+1.3.6, 2003-12-07
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added a new module 'minimal', which disables most algorithms
+  * SecureAllocator allocates a few blocks at startup
+  * A few minor MPI cleanups
+  * RPM spec file cleanups and fixes
+
+1.3.5, 2003-11-30
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Major improvements in ASN.1 string handling
+  * Added partial support for ASN.1 UTF8 STRINGs and BMP STRINGs
+  * Added partial support for the X.509v3 certificate policies extension
+  * Centralized the handling of character set information
+  * Added FIPS 140-2 startup self tests
+  * Added a module (fips140) for doing extra FIPS 140-2 tests
+  * Added FIPS 186-2 RNG
+  * Improved ASN.1 BIT STRING handling
+  * Removed a memory leak in PKCS10_Request
+  * The encoding of DirectoryString now follows PKIX guidelines
+  * Fixed some of the character set dependencies
+  * Fixed a DER encoding error for tags greater than 30
+  * The BER decoder can now handle tags larger than 30
+  * Fixed tm_hard.cpp to recognize SPARC on more systems
+  * Workarounds for a GCC 2.95.x bug in x509find.cpp
+  * RPM changed to install into /usr instead of /usr/local
+  * Added support for QNX
+
+1.2.8, 2003-11-21
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Merged several important bug fixes from 1.3.x
+
+1.3.4, 2003-11-21
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added a module that does certain MPI operations using GNU MP
+  * Added the X9.42 Diffie-Hellman PRF
+  * The Zlib and Bzip2 objects now use custom allocators
+  * Added member functions for directly hashing/MACing SecureVectors
+  * Minor optimizations to the MPI addition and subtraction algorithms
+  * Some cleanups in the low-level MPI code
+  * Created separate AES-{128,192,256} objects
+
+1.3.3, 2003-11-17
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * The library can now be repeatedly initialized and shutdown without crashing
+  * Fixed an off-by-one error in the CTS code
+  * Fixed an error in the EMSA4 verification code
+  * Fixed a memory leak in mutex.cpp (pointed out by James Widener)
+  * Fixed a memory leak in Pthread_Mutex
+  * Fixed several memory leaks in the testing code
+  * Bulletproofed the EMSA/EME/KDF/MGF retrieval functions
+  * Minor cleanups in SecureAllocator
+  * Removed a needless mutex guarding the (stateless) global timer
+  * Fixed a piece of bash-specific code in botan-config
+  * X.509 objects report more information about decoding errors
+  * Cleaned up some of the exception handling
+  * Updated the example config file with new OIDSs
+  * Moved the build instructions into a separate document, building.tex
+
+1.3.2, 2003-11-13
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a bug preventing DSA signatures from verifying on X.509 objects
+  * Made the X509_Store search routines more efficient and flexible
+  * Added a function to X509_PublicKey to do easy public/private key matching
+  * Added support for decoding indefinite length BER data
+  * Changed Pipe's peek() to take an offset
+  * Removed Filter::set_owns in favor of the new incr_owns function
+  * Removed BigInt::zero() and BigInt::one()
+  * Renamed the PEM related options from base/pem_* to pem/*
+  * Added an option to specify the line width when encoding PEM
+  * Removed the "rng/safe_longterm" option; it's always on now
+  * Changed the cipher used for RNG super-encryption from ARC4 to WiderWake4+1
+  * Cleaned up the base64/hex encoders and decoders
+  * Added an ASN.1/BER decoder as an example
+  * AES had its internals marked 'public' in previous versions
+  * Changed the value of the ASN.1 NO_OBJECT enum
+  * Various new hacks in the configure script
+  * Removed the already nominal support for SunOS
+
+1.3.1, 2003-11-04
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Generalized a few pieces of the DER encoder
+  * PKCS8::load_key would fail if handed an unencrypted key
+  * Added a failsafe so PKCS #8 key decoding can't go into an infinite loop
+
+1.3.0, 2003-11-02
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Major redesign of the PKCS #8 private key import/export system
+  * Added a small amount of UI interface code for getting passphrases
+  * Added heuristics that tell if a key, cert, etc is stored as PEM or BER
+  * Removed CS-Cipher, SHARK, ThreeWay, MD5-MAC, and EMAC
+  * Removed certain deprecated constructors of RSA, DSA, DH, RW, NR
+  * Made PEM decoding more forgiving of extra text before the header
+
+1.2.7, 2003-10-31
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added support for reading configuration files
+  * Added constructors so NR and RW keys can be imported easily
+  * Fixed mp_asm64, which was completely broken in 1.2.6
+  * Removed tm_hw_ia32 module; replaced by tm_hard
+  * Added support for loading certain oddly formed RSA certificates
+  * Fixed spelling of NON_REPUDIATION enum
+  * Renamed the option default_to_ca to v1_assume_ca
+  * Fixed a minor bug in X.509 certificate generation
+  * Fixed a latent bug in the OID lookup code
+  * Updated the RPM spec file
+  * Added to the tutorial
+
+1.2.6, 2003-07-04
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Major performance increase for PK algorithms on most 64-bit systems
+  * Cleanups in the low-level MPI code to support asm implementations
+  * Fixed build problems with some versions of Compaq's C++ compiler
+  * Removed useless constructors for NR public and private keys
+  * Removed support for the patch_file directive in module files
+  * Removed several deprecated functions
+
+1.2.5, 2003-06-22
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a tricky and long-standing memory leak in Pipe
+  * Major cleanups and fixes in the memory allocation system
+  * Removed alloc_mlock, which has been superseded by the ml_unix module
+  * Removed a denial of service vulnerability in X509_Store
+  * Fixed compilation problems with VS .NET 2003 and Codewarrior 8
+  * Added another variant of PKCS8::load_key, taking a memory buffer
+  * Fixed various minor/obscure bugs which occurred when MP_WORD_BITS != 32
+  * BigInt::operator%=(word) was a no-op if the input was a power of 2
+  * Fixed portability problems in BigInt::to_u32bit
+  * Fixed major bugs in SSL3-MAC
+  * Cleaned up some messes in the PK algorithms
+  * Cleanups and extensions for OMAC and EAX
+  * Made changes to the entropy estimation function
+  * Added a 'beos' module set for use on BeOS
+  * Officially deprecated a few X509:: and PKCS8:: functions
+  * Moved the contents of primes.h to numthry.h
+  * Moved the contents of x509opt.h to x509self.h
+  * Removed the (empty) desx.h header
+  * Documentation updates
+
+1.2.4, 2003-05-29
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a bug in EMSA1 affecting NR signature verification
+  * Fixed a few latent bugs in BigInt related to word size
+  * Removed an unused function, mp_add2_nc, from the MPI implementation
+  * Reorganized the core MPI files
+
+1.2.3, 2003-05-20
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a bug that prevented DSA/NR key generation
+  * Fixed a bug that prevented importing some root CA certs
+  * Fixed a bug in the BER decoder when handing optional bit or byte strings
+  * Fixed the encoding of authorityKeyIdentifier in X509_CA
+  * Added a sanity check in PBKDF2 for zero length passphrases
+  * Added versions of X509::load_key and PKCS8::load_key that take a file name
+  * X509_CA generates 128 bit serial numbers now
+  * Added tests to check PK key generation
+  * Added a simplistic X.509 CA example
+  * Cleaned up some of the examples
+
+1.2.2, 2003-05-13
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Add checks to prevent any BigInt bugs from revealing an RSA or RW key
+  * Changed the interface of Global_RNG::seed
+  * Major improvements for the es_unix module
+  * Added another Win32 entropy source, es_win32
+  * The Win32 CryptoAPI entropy source can now poll multiple providers
+  * Improved the BeOS entropy source
+  * Renamed pipe_unixfd module to fd_unix
+  * Fixed a file descriptor leak in the EGD module
+  * Fixed a few locking bugs
+
+1.2.1, 2003-05-06
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added ANSI X9.23 compatible CBC padding
+  * Added an entropy source using Win32 CryptoAPI
+  * Removed the Pipe I/O operators taking a FILE*
+  * Moved the BigInt encoding/decoding functions into the BigInt class
+  * Integrated several fixes for VC++ 7 (from Hany Greiss)
+  * Fixed the configure.pl script for Windows builds
+
+1.2.0, 2003-04-28
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Tweaked the Karatsuba cut-off points
+  * Increased the allowed keylength of HMAC and Blowfish
+  * Removed the 'mpi_ia32' module, pending rewrite
+  * Workaround a GCC 2.95.x bug in eme1.cpp
+
+1.1.13, 2003-04-22
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added OMAC
+  * Added EAX authenticated cipher mode
+  * Diffie-Hellman would not do blinding in some cases
+  * Optimized the OFB and CTR modes
+  * Corrected Skipjack's word ordering, as per NIST clarification
+  * Support for all subject/issuer attribute types required by RFC 3280
+  * The removeFromCRL CRL reason code is now handled correctly
+  * Increased the flexibility of the allocators
+  * Renamed Rijndael to AES, created aes.h, deleted rijndael.h
+  * Removed support for the 'no_timer' LibraryInitializer option
+  * Removed 'es_pthr' module, pending further testing
+  * Cleaned up get_ciph.cpp
+
+1.1.12, 2003-04-15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a ASN.1 string encoding bug
+  * Fixed a pair of X509_DN encoding problems
+  * Base64_Decoder and Hex_Decoder can now validate input
+  * Removed support for the LibraryInitializer option 'egd_path'
+  * Added tests for DSA X.509 and PKCS #8 key formats
+  * Removed a long deprecated feature of DH_PrivateKey's constructor
+  * Updated the RPM .spec file
+  * Major documentation updates
+
+1.1.11, 2003-04-07
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added PKCS #10 certificate requests
+  * Changed X509_Store searching interface to be more flexible
+  * Added a generic Certificate_Store interface
+  * Added a function for generating self-signed X.509 certs
+  * Cleanups and changes to X509_CA
+  * New examples for PKCS #10 and self-signed certificates
+  * Some documentation updates
+
+1.1.10, 2003-04-03
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * X509_CA can now generate new X.509 CRLs
+  * Added blinding for RSA, RW, DH, and ElGamal to prevent timing attacks
+  * More certificate and CRL extensions/attributes are supported
+  * Better DN handling in X.509 certificates/CRLs
+  * Added a DataSink hierarchy (suggested by Jim Darby)
+  * Consolidated SecureAllocator and ManagedAllocator
+  * Many cleanups and generalizations
+  * Added a (slow) pthreads based EntropySource
+  * Fixed some threading bugs
+
+1.1.9, 2003-02-25
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added support for using X.509v2 CRLs
+  * Fixed several bugs in the path validation algorithm
+  * Certificates can be verified for a particular usage
+  * Algorithm for comparing distinguished names now follows X.509
+  * Cleaned up the code for the es_beos, es_ftw, es_unix modules
+  * Documentation updates
+
+1.1.8, 2003-01-29
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixes for the certificate path validation algorithm in X509_Store
+  * Fixed a bug affecting X509_Certificate::is_ca_cert()
+  * Added a general configuration interface for policy issues
+  * Cleanups and API changes in the X.509 CA, cert, and store code
+  * Made various options available for X509_CA users
+  * Changed X509_Time's interface to work around time_t problems
+  * Fixed a theoretical weakness in Randpool's entropy mixing function
+  * Fixed problems compiling with GCC 2.95.3 and GCC 2.96
+  * Fixed a configure bug (reported by Jon Wilson) affecting MinGW
+
+1.1.7, 2003-01-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed an obscure but dangerous bug in SecureVector::swap
+  * Consolidated SHA-384 and SHA-512 to save code space
+  * Added SSL3-MAC and SSL3-PRF
+  * Documentation updates, including a new tutorial
+
+1.0.2, 2003-01-12
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed an obscure SEGFAULT causing bug in Pipe
+  * Fixed an obscure but dangerous bug in SecureVector::swap
+
+2002
+----------------------------------------
+
+1.1.6, 2002-12-10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Initial support for X.509v3 certificates and CAs
+  * Major redesign/rewrite of the ASN.1 encoding/decoding code
+  * Added handling for DSA/NR signatures encoded as DER SEQUENCEs
+  * Documented the generic cipher lookup interface
+  * Added an (untested) entropy source for BeOS
+  * Various cleanups and bug fixes
+
+1.1.5, 2002-11-17
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added the discrete logarithm integrated encryption system (DLIES)
+  * Various optimizations for BigInt
+  * Added support for assembler optimizations in modules
+  * Added BigInt x86 optimizations module (mpi_ia32)
+
+1.1.4, 2002-11-10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Speedup of 15-30% for PK algorithms
+  * Implemented the PBES2 encryption scheme
+  * Fixed a potential bug in decoding RSA and RW private keys
+  * Changed the DL_Group class interface to handle different formats better
+  * Added support for PKCS #3 encoded DH parameters
+  * X9.42 DH parameters use a PEM label of 'X942 DH PARAMETERS'
+  * Added key pair consistency checking
+  * Fixed a compatibility problem with gcc 2.96 (pointed out by Hany Greiss)
+  * A botan-config script is generated at configure time
+  * Documentation updates
+
+1.1.3, 2002-11-03
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added a generic public/private key loading interface
+  * Fixed a small encoding bug in RSA, RW, and DH
+  * Changed the PK encryption/decryption interface classes
+  * ECB supports using padding methods
+  * Added a function-based interface for library initialization
+  * Added support for RIPEMD-128 and Tiger PKCS#1 v1.5 signatures
+  * The cipher mode benchmarks now use 128-bit AES instead of DES
+  * Removed some obsolete typedefs
+  * Removed OpenCL support (opencl.h, the OPENCL_* macros, etc)
+  * Added tests for PKCS #8 encoding/decoding
+  * Added more tests for ECB and CBC
+
+1.1.2, 2002-10-21
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Support for PKCS #8 encoded RSA, DSA, and DH private keys
+  * Support for Diffie-Hellman X.509 public keys
+  * Major reorganization of how X.509 keys are handled
+  * Added PKCS #5 v2.0's PBES1 encryption scheme
+  * Added a generic cipher lookup interface
+  * Added the WiderWake4+1 stream cipher
+  * Added support for sync-able stream ciphers
+  * Added a 'paranoia level' option for the LibraryInitializer
+  * More security for RNG output meant for long term keys
+  * Added documentation for some of the new 1.1.x features
+  * CFB's feedback argument is now specified in bits
+  * Renamed CTR class to CTR_BE
+  * Updated the RSA and DSA examples to use X.509 and PKCS #8 key formats
+
+1.1.1, 2002-10-15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added the Korean hash function HAS-160
+  * Partial support for RSA and DSA X.509 public keys
+  * Added a mostly functional BER encoder/decoder
+  * Added support for non-deterministic MAC functions
+  * Initial support for PEM encoding/decoding
+  * Internal cleanups in the PK algorithms
+  * Several new convenience functions in Pipe
+  * Fixed two nasty bugs in Pipe
+  * Messed with the entropy sources for es_unix
+  * Discrete logarithm groups are checked for safety more closely now
+  * For compatibility with GnuPG, ElGamal now supports DSA-style groups
+
+1.1.0, 2002-09-14
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added entropy estimation to the RNGs
+  * Improved the overall design of both Randpool and ANSI_X917_RNG
+  * Added a separate RNG for nonce generation
+  * Added window exponentiation support in power_mod
+  * Added a get_s2k function and the PKCS #5 S2K algorithms
+  * Added the TLSv1 PRF
+  * Replaced BlockCipherModeIV typedef with InitializationVector class
+  * Renamed PK_Key_Agreement_Scheme to PK_Key_Agreement
+  * Renamed SHA1 -> SHA_160 and SHA2_x -> SHA_x
+  * Added support for RIPEMD-160 PKCS#1 v1.5 signatures
+  * Changed the key agreement scheme interface
+  * Changed the S2K and KDF interfaces
+  * Better SCAN compatibility for HAVAL, Tiger, MISTY1, SEAL, RC5, SAFER-SK
+  * Added support for variable-pass Tiger
+  * Major speedup for Rabin-Williams key generation
+
+1.0.1, 2002-09-14
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed a minor bug in Randpool::random()
+  * Added some new aliases and typedefs for 1.1.x compatibility
+  * The 4096-bit RSA benchmark key was decimal instead of hex
+  * EMAC was returning an incorrect name
+
+1.0.0, 2002-08-26
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Octal I/O of BigInt is now supported
+  * Fixed portability problems in the es_egd module
+  * Generalized IV handling in the block cipher modes
+  * Added Karatsuba multiplication and k-ary exponentiation
+  * Fixed a problem in the multiplication routines
+
+0.9.2, 2002-08-18
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * DH_PrivateKey::public_value() was returning the wrong value
+  * Various BigInt optimizations
+  * The filters.h header now includes hex.h and base64.h
+  * Moved Counter mode to ctr.h
+  * Fixed a couple minor problems with VC++ 7
+  * Fixed problems with the RPM spec file
+
+0.9.1, 2002-08-10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Grand rename from OpenCL to Botan
+  * Major optimizations for the PK algorithms
+  * Added ElGamal encryption
+  * Added Whirlpool
+  * Tweaked memory allocation parameters
+  * Improved the method of seeding the global RNG
+  * Moved pkcs1.h to eme_pkcs.h
+  * Added more test vectors for some algorithms
+  * Fixed error reporting in the BigInt tests
+  * Removed Default_Timer, it was pointless
+  * Added some new example applications
+  * Removed some old examples that weren't that interesting
+  * Documented the compression modules
+
+0.9.0, 2002-08-03
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * EMSA4 supports variable salt size
+  * PK_* can take a string naming the encoding method to use
+  * Started writing some internals documentation
+
+0.8.7, 2002-07-30
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed bugs in EME1 and EMSA4
+  * Fixed a potential crash at shutdown
+  * Cipher modes returned an ill-formed name
+  * Removed various deprecated types and headers
+  * Cleaned up the Pipe interface a bit
+  * Minor additions to the documentation
+  * First stab at a Visual C++ makefile (doc/Makefile.vc7)
+
+0.8.6, 2002-07-25
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added EMSA4 (aka PSS)
+  * Brought the manual up to date; many corrections and additions
+  * Added a parallel hash function construction
+  * Lookup supports all available algorithms now
+  * Lazy initialization of the lookup tables
+  * Made more discrete logarithm groups available through get_dl_group()
+  * StreamCipher_Filter supports seeking (if the underlying cipher does)
+  * Minor optimization for GCD calculations
+  * Renamed SAFER_SK128 to SAFER_SK
+  * Removed many previously deprecated functions
+  * Some now-obsolete functions, headers, and types have been deprecated
+  * Fixed some bugs in DSA prime generation
+  * DL_Group had a constructor for DSA-style prime gen but it wasn't defined
+  * Reversed the ordering of the two arguments to SEAL's constructor
+  * Fixed a threading problem in the PK algorithms
+  * Fixed a minor memory leak in lookup.cpp
+  * Fixed pk_types.h (it was broken in 0.8.5)
+  * Made validation tests more verbose
+  * Updated the check and example applications
+
+0.8.5, 2002-07-21
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Major changes to constructors for DL-based cryptosystems (DSA, NR, DH)
+  * Added a DL_Group class
+  * Reworking of the pubkey internals
+  * Support in lookup for aliases and PK algorithms
+  * Renamed CAST5 to CAST_128 and CAST256 to CAST_256
+  * Added EMSA1
+  * Reorganization of header files
+  * LibraryInitializer will install new allocator types if requested
+  * Fixed a bug in Diffie-Hellman key generation
+  * Did a workaround in pipe.cpp for GCC 2.95.x on Linux
+  * Removed some debugging code from init.cpp that made FTW ES useless
+  * Better checking for invalid arguments in the PK algorithms
+  * Reduced Base64 and Hex default line length (if line breaking is used)
+  * Fixes for HP's aCC compiler
+  * Cleanups in BigInt
+
+0.8.4, 2002-07-14
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added Nyberg-Rueppel signatures
+  * Added Diffie-Hellman key exchange (kex interface is subject to change)
+  * Added KDF2
+  * Enhancements to the lookup API
+  * Many things formerly taking pointers to algorithms now take names
+  * Speedups for prime generation
+  * LibraryInitializer has support for seeding the global RNG
+  * Reduced SAFER-SK128 memory consumption
+  * Reversed the ordering of public and private key values in DSA constructor
+  * Fixed serious bugs in MemoryMapping_Allocator
+  * Fixed memory leak in Lion
+  * FTW_EntropySource was not closing the files it read
+  * Fixed line breaking problem in Hex_Encoder
+
+0.8.3, 2002-06-09
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added DSA and Rabin-Williams signature schemes
+  * Added EMSA3
+  * Added PKCS#1 v1.5 encryption padding
+  * Added Filters for PK algorithms
+  * Added a Keyed_Filter class
+  * LibraryInitializer processes arguments now
+  * Major revamp of the PK interface classes
+  * Changed almost all of the Filters for non-template operation
+  * Changed HMAC, Lion, Luby-Rackoff to non-template classes
+  * Some fairly minor BigInt optimizations
+  * Added simple benchmarking for PK algorithms
+  * Added hooks for fixed base and fixed exponent modular exponentiation
+  * Added some examples for using RSA
+  * Numerous bugfixes and cleanups
+  * Documentation updates
+
+0.8.2, 2002-05-18
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added an (experimental) algorithm lookup interface
+  * Added code for directly testing BigInt
+  * Added SHA2-384
+  * Optimized SHA2-512
+  * Major optimization for Adler32 (thanks to Dan Nicolaescu)
+  * Various minor optimizations in BigInt and related areas
+  * Fixed two bugs in X9.19 MAC, both reported by Darren Starsmore
+  * Fixed a bug in BufferingFilter
+  * Made a few fixes for MacOS X
+  * Added a workaround in configure.pl for GCC 2.95.x
+  * Better support for PowerPC, ARM, and Alpha
+  * Some more cleanups
+
+0.8.1, 2002-05-06
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Major code cleanup (check doc/deprecated.txt)
+  * Various bugs fixed, including several portability problems
+  * Renamed MessageAuthCode to MessageAuthenticationCode
+  * A replacement for X917 is in x917_rng.h
+  * Changed EMAC to non-template class
+  * Added ANSI X9.19 compatible CBC-MAC
+  * TripleDES now supports 128 bit keys
+
+0.8.0, 2002-04-24
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Merged BigInt: many bugfixes and optimizations since alpha2
+  * Added RSA (rsa.h)
+  * Added EMSA2 (emsa2.h)
+  * Lots of new interface code for public key algorithms (pk_base.h, pubkey.h)
+  * Changed some interfaces, including SymmetricKey, to support the global rng
+  * Fixed a serious bug in ManagedAllocator
+  * Renamed RIPEMD128 to RIPEMD_128 and RIPEMD160 to RIPEMD_160
+  * Removed some deprecated stuff
+  * Added a global random number generator (rng.h)
+  * Added clone functions to most of the basic algorithms
+  * Added a library initializer class (init.h)
+  * Version macros in version.h
+  * Moved the base classes from opencl.h to base.h
+  * Renamed the bzip2 module to comp_bzip2 and zlib to comp_zlib
+  * Documentation updates for the new stuff (still incomplete)
+  * Many new deprecated things: check doc/deprecated.txt
+
+0.7.10, 2002-04-07
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Added EGD_EntropySource module (es_egd)
+  * Added a file tree walking EntropySource (es_ftw)
+  * Added MemoryLocking_Allocator module (alloc_mlock)
+  * Renamed the pthr_mux, unix_rnd, and mmap_mem modules
+  * Changed timer mechanism; the clock method can be switched on the fly.
+  * Renamed MmapDisk_Allocator to MemoryMapping_Allocator
+  * Renamed ent_file.h to es_file.h (ent_file.h is around, but deprecated)
+  * Fixed several bugs in MemoryMapping_Allocator
+  * Added more default sources for Unix_EntropySource
+  * Changed SecureBuffer to use same allocation methods as SecureVector
+  * Added bigint_divcore into mp_core to support BigInt alpha2 release
+  * Removed some Pipe functions deprecated since 0.7.8
+  * Some fixes for the configure program
+
+0.7.9, 2002-03-19
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Memory allocation substantially revamped
+  * Added memory allocation method based on mmap(2) in the mmap_mem module
+  * Added ECB and CTS block cipher modes (ecb.h, cts.h)
+  * Added a Mutex interface (mutex.h)
+  * Added module pthr_mux, implementing the Mutex interface
+  * Added Threaded Filter interface (thr_filt.h)
+  * All algorithms can now by keyed with SymmetricKey objects
+  * More testing occurs with --validate (expected failures)
+  * Fixed two bugs reported by Hany Greiss, in Luby-Rackoff and RC6
+  * Fixed a buffering bug in Bzip_Decompress and Zlib_Decompress
+  * Made X917 safer (and about 1/3 as fast)
+  * Documentation updates
+
+0.7.8, 2002-02-28
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * More capabilities for Pipe, inspired by SysV STREAMS, including peeking,
+    better buffering, and stack ops. NOT BACKWARDS COMPATIBLE: SEE DOCUMENTATION
+  * Added a BufferingFilter class
+  * Added popen() based EntropySource for generic Unix systems (unix_rnd)
+  * Moved 'devrand' module into main distribution (ent_file.h), renamed to
+    File_EntropySource, and changed interface somewhat.
+  * Made Randpool somewhat more conservative and also 25% faster
+  * Minor fixes and updates for the configure script
+  * Added some tweaks for memory allocation
+  * Documentation updates for the new Pipe interface
+  * Fixed various minor bugs
+  * Added a couple of new example programs (stack and hasher2)
+
+2001
+----------------------------------------
+
+0.7.7, 2001-11-24
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Filter::send now works in the constructor of a Filter subclass
+  * You may now have to include <opencl/pipe.h> explicitly in some code
+  * Added preliminary PK infrastructure classes in pubkey.h and pkbase.h
+  * Enhancements to SecureVector (append, destroy functions)
+  * New infrastructure for secure memory allocation
+  * Added IEEE P1363 primitives MGF1, EME1, KDF1
+  * Rijndael optimizations and cleanups
+  * Changed CipherMode<B> to BlockCipherMode(B*)
+  * Fixed a nasty bug in pipe_unixfd
+  * Added portions of the BigInt code into the main library
+  * Support for VAX, SH, POWER, PowerPC-64, Intel C++
+
+0.7.6, 2001-10-14
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fixed several serious bugs in SecureVector created in 0.7.5
+  * Square optimizations
+  * Fixed shared objects on MacOS X and HP-UX
+  * Fixed static libs for KCC 4.0; works with KCC 3.4g as well
+  * Full support for Athlon and K6 processors using GCC
+  * Added a table of prime numbers < 2**16 (primes.h)
+  * Some minor documentation updates
+
+0.7.5, 2001-08-19
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Split checksum.h into adler32.h, crc24.h, and crc32.h
+  * Split modes.h into cbc.h, cfb.h, and ofb.h
+  * CBC_wPadding* has been replaced by CBC_Encryption and CBC_Decryption
+  * Added OneAndZeros and NoPadding methods for CBC
+  * Added Lion, a very fast block cipher construction
+  * Added an S2K base class (s2k.h) and an OpenPGP_S2K class (pgp_s2k.h)
+  * Basic types (ciphers, hashes, etc) know their names now (call name())
+  * Changed the EntropySource type somewhat
+  * Big speed-ups for ISAAC, Adler32, CRC24, and CRC32
+  * Optimized CAST-256, DES, SAFER-SK, Serpent, SEAL, MD2, and RIPEMD-160
+  * Some semantics of SecureVector have changed slightly
+  * The mlock module has been removed for the time being
+  * Added string handling functions for hashes and MACs
+  * Various non-user-visible cleanups
+  * Shared library soname is now set to the full version number
+
+0.7.4, 2001-07-15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * New modules: Zlib, gettimeofday and x86 RTC timers, Unix I/O for Pipe
+  * Fixed a vast number of errors in the config script/makefile/specfile
+  * Pipe now has a stdio(3) interface as well as C++ iostreams
+  * ARC4 supports skipping the first N bytes of the cipher stream (ala MARK4)
+  * Bzip2 supports decompressing multiple concatenated streams, and flushing
+  * Added a simple 'overall average' score to the benchmarks
+  * Fixed a small bug in the POSIX timer module
+  * Removed a very-unlikely-to-occur bug in most of the hash functions
+  * filtbase.h now includes <iosfwd>, not <iostream>
+  * Minor documentation updates
+
+0.7.3, 2001-06-08
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Fix build problems on Solaris/SPARC
+  * Fix build problems with Perl versions < 5.6
+  * Fixed some stupid code that broke on a few compilers
+  * Added string handling functions to Pipe
+  * MISTY1 optimizations
+
+0.7.2, 2001-06-03
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Build system supports modules
+  * Added modules for mlock, a /dev/random EntropySource, POSIX1.b timers
+  * Added Bzip2 compression filter, contributed by Peter Jones
+  * GNU make no longer required (tested with 4.4BSD pmake and Solaris make)
+  * Fixed minor bug in several of the hash functions
+  * Various other minor fixes and changes
+  * Updates to the documentation
+
+0.7.1, 2001-05-16
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Rewrote configure script: more consistent and complete
+  * Made it easier to find out parameters of types at run time (opencl.h)
+  * New functions for finding the version being used (version.h)
+  * New SymmetricKey interface for Filters (symkey.h)
+  * InvalidKeyLength now records what the invalid key length was
+  * Optimized DES, CS-Cipher, MISTY1, Skipjack, XTEA
+  * Changed GOST to use correct S-box ordering (incompatible change)
+  * Benchmark code was almost totally rewritten
+  * Many more entries in the test vector file
+  * Fixed minor and idiotic bug in check.cpp
+
+0.7.0, 2001-03-01
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * First public release
 
diff --git a/doc/lowlevel.txt b/doc/lowlevel.txt
new file mode 100644
index 000000000..4f63948da
--- /dev/null
+++ b/doc/lowlevel.txt
@@ -0,0 +1,641 @@
+
+The Low-Level Interface
+=================================
+
+Botan has two different interfaces. The one documented in this section is meant
+more for implementing higher-level types (see the section on filters, earlier in
+this manual) than for use by applications. Using it safely requires a solid
+knowledge of encryption techniques and best practices, so unless you know, for
+example, what CBC mode and nonces are, and why PKCS #1 padding is important,
+you should avoid this interface in favor of something working at a higher level
+(such as the CMS interface).
+
+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()
+
+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()
+
+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()
+
+This function is central to Botan's name-based interface. The
+``clone`` has many different return types, such as ``BlockCipher``\*
+and ``HashFunction``\*, depending on what kind of object it is called
+on. Note that unlike Java's clone, this returns a new object in a
+"pristine" state; that is, operations done on the initial object
+before calling ``clone`` do not affect the initial state of the new
+clone.
+
+Cloned objects can (and should) be deallocated with the C++ ``delete``
+operator.
+
+Keys and IVs
+---------------------------------
+
+Both symmetric keys and initialization values can be considered byte
+(or octet) strings. These are represented by the classes
+``SymmetricKey`` and ``InitializationVector``, which are
+subclasses of ``OctetString``.
+
+Since often it's hard to distinguish between a key and IV, many things
+(such as key derivation mechanisms) return ``OctetString`` instead of
+``SymmetricKey`` to allow its use as a key or an IV.
+
+.. cpp:function:: OctetString::OctetString(RandomNumberGenerator& rng, size_t length)
+
+  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.
+
+.. cpp:function:: OctetString::OctetString(const byte* input, size_t length)
+
+  This constructor copies its input.
+
+Symmetrically Keyed Algorithms
+---------------------------------
+
+Block ciphers, stream ciphers, and MACs are all keyed operations; to
+be useful, they have to be set to use a particular key, which is a
+randomly chosen string of bits of a specified length.  The length
+required by any particular algorithm may vary, depending on both the
+algorithm specification and the implementation. You can query any
+botan object to find out what key length(s) it supports.
+
+To make this similarity in terms of keying explicit, all algorithms of
+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)
+
+  This sets the key to the value specified. Most algorithms only
+  accept keys of certain lengths. If you attempt to call ``set_key``
+  with a key length that is not supported, the exception
+  ``Invalid_Key_Length`` will be thrown. There is also another version
+  of ``set_key`` that takes a ``SymmetricKey`` as an argument.
+
+  In all cases, ``set_key`` must be called on an object before any
+  data processing (encryption, decryption, etc) is done by that
+  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
+
+  This function returns true if and only if ``length`` is a valid keylength
+  for the algorithm.
+
+.. cpp:function:: size_t minimum_keylength() const
+
+  Return the smallest key length (in bytes) that is acceptible for the
+  algorithm.
+
+.. cpp:function:: size_t maximum_keylength() const
+
+  Return the largest key length (in bytes) that is acceptible for the
+  algorithm
+
+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
+
+  Returns the block size of the cipher in bytes
+
+.. cpp: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
+
+  Encrypt a single block, taking the input from ``in`` and placing it
+  in ``out``.
+
+.. cpp: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
+
+  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
+
+  Decrypt a single block, taking the input from ``in`` and placing it
+  in ``out``.
+
+.. cpp:function:: void decrypt(byte* block) const
+
+  Identical to ``decrypt(block, block)``.
+
+
+Stream Ciphers
+---------------------------------
+
+Stream ciphers are somewhat different from block ciphers, in that
+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 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.
+
+.. cpp:function:: size_t output_length()
+
+Return the size of the output of this function.
+
+.. cpp:function:: void update(const byte* input, size_t length)
+
+.. cpp:function:: void update(byte input)
+
+.. cpp:function:: void update(const std::string& input)
+
+Updates the hash/mac calculation with ``input``.
+
+.. cpp:function:: void final(byte* out)
+
+.. cpp:function:: SecureVector<byte> final()
+
+Complete the hash/MAC calculation and place the result into ``out``.
+For the argument taking an array, exactly ``output_length`` bytes will
+be written. After you call ``final``, the hash function is reset to
+its initial state, so it may be reused immediately.
+
+The second method of using final is to call it with no arguments at
+all, as shown in the second prototype. It will return the hash/mac
+value in a memory buffer.
+
+There is also a pair of functions called ``process``. They are
+a combination of a single ``update``, and ``final``.
+Both versions return the final value, rather than placing it an
+array. Calling ``process`` with a single byte value isn't
+available, mostly because it would rarely be useful.
+
+A MAC can be viewed (in most cases) as a keyed hash function, so
+classes that are derived from ``MessageAuthenticationCode`` have
+``update`` and ``final`` classes just like a
+``HashFunction`` (and like a ``HashFunction``, after
+``final`` is called, it can be used to make a new MAC right
+away; the key is kept around).
+
+A MAC has the ``SymmetricAlgorithm`` interface in addition to the
+``BufferedComputation`` interface.
+
+Random Number Generators
+---------------------------------
+
+The random number generators provided in Botan are meant for creating
+keys, IVs, padding, nonces, and anything else that requires 'random'
+data. It is important to remember that the output of these classes
+will vary, even if they are supplied with ethe same seed (ie, two
+``Randpool`` objects with similar initial states will not produce
+the same output, because the value of high resolution timers is added
+to the state at various points).
+
+To ensure good quality output, a PRNG needs to be seeded with truly
+random data (such as that produced by a hardware RNG). Typically, you
+will use an ``EntropySource`` (see below). To add some (typically
+application specific) entropy to a PRNG, you can use
+
+.. cpp:function:: void add_entropy(const byte* data, size_t length)
+
+Once a PRNG has been initialized, you can get a single byte of random
+data by
+
+.. cpp:function:: byte random()
+
+or get a large block by calling
+
+.. cpp:function:: void randomize(byte* data, size_t length)
+
+Randpool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``Randpool`` is the primary PRNG within Botan. In recent versions all
+uses of it have been wrapped by an implementation of the X9.31 PRNG
+(see below). If for some reason you should have cause to create a PRNG
+instead of using the "global" one owned by the library, it would be
+wise to consider the same on the grounds of general caution; while
+``Randpool`` is designed with known attacks and PRNG weaknesses in
+mind, it is not an standard/official PRNG. The remainder of this
+section is a (fairly technical, though high-level) description of the
+algorithms used in this PRNG. Unless you have a specific interest in
+this subject, the rest of this section might prove somewhat
+uninteresting.
+
+``Randpool`` has an internal state called pool, which is 512 bytes
+long. This is where entropy is mixed into and extracted from. There is also a
+small output buffer (called buffer), which holds the data which has already
+been generated but has just not been output yet.
+
+It is based around a MAC and a block cipher (which are currently
+HMAC(SHA-256) and AES-256). Where a specific size is mentioned, it
+should be taken as a multiple of the cipher's block size. For example,
+if a 256-bit block cipher were used instead of AES, all the sizes
+internally would double. Every time some new output is needed, we
+compute the MAC of a counter and a high resolution timer. The
+resulting MAC is XORed into the output buffer (wrapping as needed),
+and the output buffer is then encrypted with AES, producing 16 bytes
+of output.
+
+After 8 blocks (or 128 bytes) have been produced, we mix the pool. To
+do this, we first rekey both the MAC and the cipher; the new MAC key
+is the MAC of the current pool under the old MAC key, while the new
+cipher key is the MAC of the current pool under the just-chosen MAC
+key. We then encrypt the entire pool in CBC mode, using the current
+(unused) output buffer as the IV. We then generate a new output
+buffer, using the mechanism described in the previous paragraph.
+
+To add randomness to the PRNG, we compute the MAC of the input and XOR
+the output into the start of the pool. Then we remix the pool and
+produce a new output buffer. The initial MAC operation should make it
+very hard for chosen inputs to harm the security of ``Randpool``, and
+as HMAC should be able to hold roughly 256 bits of state, it is
+unlikely that we are wasting much input entropy (or, if we are, it
+doesn't matter, because we have a very abundant supply).
+
+ANSI X9.31
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``ANSI_X931_PRNG`` is the standard issue X9.31 Appendix A.2.4 PRNG,
+though using AES-256 instead of 3DES as the block cipher. This PRNG
+implementation has been checked against official X9.31 test vectors.
+
+Internally, the PRNG holds a pointer to another PRNG (typically
+Randpool). This internal PRNG generates the key and seed used by the
+X9.31 algorithm, as well as the date/time vectors. Each time an X9.31
+PRNG object receives entropy, it passes it along to the PRNG it is
+holding, and then pulls out some random bits to generate a new key and
+seed. This PRNG considers itself seeded as soon as the internal PRNG
+is seeded.
+
+
+Entropy Sources
+---------------------------------
+
+An ``EntropySource`` is an abstract representation of some method of
+gather "real" entropy. This tends to be very system dependent. The
+*only* way you should use an ``EntropySource`` is to pass it to a PRNG
+that will extract entropy from it -- never use the output directly for
+any kind of key or nonce generation!
+
+``EntropySource`` has a pair of functions for getting entropy from
+some external source, called ``fast_poll`` and ``slow_poll``. These
+pass a buffer of bytes to be written; the functions then return how
+many bytes of entropy were gathered.
+
+Note for writers of ``EntropySource`` subclasses: it isn't necessary
+to use any kind of cryptographic hash on your output. The data
+produced by an EntropySource is only used by an application after it
+has been hashed by the ``RandomNumberGenerator`` that asked for the
+entropy, thus any hashing you do will be wasteful of both CPU cycles
+and entropy.
+
+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.
+
+PBKDF Algorithms
+---------------------------------
+
+There are various procedures (usually ad-hoc) for turning a
+passphrase into a (mostly) arbitrary length key for a symmetric
+cipher. A general interface for such algorithms is presented in
+``pbkdf.h``. The main function is ``derive_key``, which
+takes a passphrase, a salt, an iteration count, and the desired length
+of the output key, and returns a key of that length, deterministically
+produced from the passphrase and salt. If an algorithm can't produce a
+key of that size, it will throw an exception (most notably, PKCS #5's
+PBKDF1 can only produce strings between 1 and $n$ bytes, where $n$ is
+the output size of the underlying hash function).
+
+The purpose of the iteration count is to make the algorithm take
+longer to compute the final key (reducing the speed of brute-force
+attacks of various kinds). Most standards recommend an iteration count
+of at least 10000. Currently defined PBKDF algorithms are
+"PBKDF1(digest)", "PBKDF2(digest)", and "OpenPGP-S2K(digest)"; you can
+retrieve any of these using the ``get_pbkdf``, found in
+``lookup.h``. As of this writing, "PBKDF2(SHA-256)" with 10000
+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
+strange manner; instead of specifying how many times to iterate the
+hash, it tells how many *bytes* should be hashed in total
+(including the salt). So the exact iteration count will depend on the
+size of the salt (which is fixed at 8 bytes by the OpenPGP standard,
+though the implementation will allow any salt size) and the size of
+the passphrase.
+
+To get what OpenPGP calls "Simple S2K", set iterations to 0, and do
+not specify a salt. To get "Salted S2K", again leave the iteration
+count at 0, but give an 8-byte salt. "Salted and Iterated S2K"
+requires an 8-byte salt and some iteration count (this should be
+significantly larger than the size of the longest passphrase that
+might reasonably be used; somewhere from 1024 to 65536 would probably
+be about right). Using both a reasonably sized salt and a large
+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
+database in which the passwords are stored, they immediately gain
+access to all of them. Often passwords are reused among multiple
+services or machines, meaning once a password to a single service is
+known an attacker has a substantial head start on attacking other
+machines.
+
+The general approach is to store, instead of the password, the output
+of a one way function of the password. Upon receiving an
+authentication request, the authenticator can recompute the one way
+function and compare the value just computed with the one that was
+stored. If they match, then the authentication request succeeds. But
+when an attacker gains access to the database, they only have the
+output of the one way function, not the original password.
+
+Common hash functions such as SHA-256 are one way, but used alone they
+have problems for this purpose. What an attacker can do, upon gaining
+access to such a stored password database, is hash common dictionary
+words and other possible passwords, storing them in a list. Then he
+can search through his list; if a stored hash and an entry in his list
+match, then he has found the password. Even worse, this can happen
+*offline*: an attacker can begin hashing common passwords days,
+months, or years before ever gaining access to the database. In
+addition, if two users choose the same password, the one way function
+output will be the same for both of them, which will be visible upon
+inspection of the database.
+
+There are two solutions to these problems: salting and
+iteration. Salting refers to including, along with the password, a
+randomly chosen value which perturbs the one way function. Salting can
+reduce the effectivness of offline dictionary generation (because for
+each potential password, an attacker would have to compute the one way
+function output for all possible salts - with a large enough salt,
+this can make the problem quite difficult). It also prevents the same
+password from producing the same output, as long as the salts do not
+collide. With a large salt (say 80 to 128 bits) this will be quite
+unlikely. Iteration refers to the general technique of forcing
+multiple one way function evaluations when computing the output, to
+slow down the operation. For instance if hashing a single password
+requires running SHA-256 100,000 times instead of just once, that will
+slow down user authentication by a factor of 100,000, but user
+authentication happens quite rarely, and usually there are more
+expensive operations that need to occur anyway (network and database
+I/O, etc). On the other hand, an attacker who is attempting to break a
+database full of stolen password hashes will be seriously
+inconvenienced by a factor of 100,000 slowdown; they will be able to
+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, passhash9 and bcrypt
+
+Passhash9
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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:
+
+.. cpp:function:: std::string generate_passhash9(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.
+
+.. 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)").
+
+.. cpp:function:: bool check_passhash9(const std::string& password, const std::string& hash)
+
+   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).
+
+Bcrypt
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+
+.. cpp:function:: std::string generate_bcrypt(const std::string& password, RandomNumberGenerator& rng, u16bit work_factor = 10)
+
+and
+
+.. cpp:function:: bool check_bcrypt(const std::string& password, const std::string& hash)
+
+These work in exactly the same way as the passhash9 password hashing
+functions.
+
+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
+---------------------------------
+
+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
+---------------------------------
+
+A major concern with mixing modern multiuser OSes and cryptographic
+code is that at any time the code (including secret keys) could be
+swapped to disk, where it can later be read by an attacker. Botan
+stores almost everything (and especially anything sensitive) in memory
+buffers that a) clear out their contents when their destructors are
+called, and b) have easy plugins for various memory locking functions,
+such as the ``mlock`` call on many Unix systems.
+
+Two of the allocation method used ("malloc" and "mmap") don't
+require any extra privileges on Unix, but locking memory does. At
+startup, each allocator type will attempt to allocate a few blocks
+(typically totaling 128k), so if you want, you can run your
+application ``setuid`` ``root``, and then drop privileges
+immediately after creating your ``LibraryInitializer``. If you end
+up using more than what's been allocated, some of your sensitive data
+might end up being swappable, but that beats running as ``root``
+all the time.
+
+These classes should also be used within your own code for storing
+sensitive data. They are only meant for primitive data types (int,
+long, etc): if you want a container of higher level Botan objects, you
+can just use a ``std::vector``, since these objects know how to clear
+themselves when they are destroyed. You cannot, however, have a
+``std::vector`` (or any other container) of ``Pipe`` objects or
+filters, because these types have pointers to other filters, and
+implementing copy constructors for these types would be both hard and
+quite expensive (vectors of pointers to such objects is fine, though).
+
+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;``).
+
+``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
+---------------------------------
+
+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.
+
+At start time, the only allocator known is a ``Default_Allocator``,
+which just allocates memory using ``malloc``, and zeroizes it when the
+memory is released. It is known by the name "malloc". If you ask for
+another type of allocator ("locking" and "mmap" are currently used),
+and it is not available, some other allocator will be returned.
+
+You can add in a new allocator type using ``add_allocator_type``. This
+function takes a string and a pointer to an allocator. The string gives this
+allocator type a name to which it can be referred when one is requesting it
+with ``get_allocator``. If an error occurs (such as the name being
+already registered), this function returns false. It will return true if the
+allocator was successfully registered. If you ask it to,
+``LibraryInitializer`` will do this for you.
+
+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/architecture.pdf b/doc/old/architecture.pdf
index f0edc3fc1..f0edc3fc1 100644
--- a/doc/architecture.pdf
+++ b/doc/old/architecture.pdf
diff --git a/doc/insito_manual.pdf b/doc/old/insito_manual.pdf
index b07146992..b07146992 100644
--- a/doc/insito_manual.pdf
+++ b/doc/old/insito_manual.pdf
diff --git a/doc/tutorial.tex b/doc/old/tutorial.tex
index f220d765a..f220d765a 100644
--- a/doc/tutorial.tex
+++ b/doc/old/tutorial.tex
diff --git a/doc/tutorial2.tex b/doc/old/tutorial2.tex
index 840679d10..840679d10 100644
--- a/doc/tutorial2.tex
+++ b/doc/old/tutorial2.tex
diff --git a/doc/pgpkeys.txt b/doc/pgpkeys.txt
index 8da1d1d05..1d2f3debc 100644
--- a/doc/pgpkeys.txt
+++ b/doc/pgpkeys.txt
@@ -1,36 +1,41 @@
 
-pub   2048R/EFBADFBC 2004-10-30
-      Key fingerprint = 621D AF64 11E1 851C 4CF9  A2E1 6211 EBF1 EFBA DFBC
-uid                  Botan Distribution Key
+PGP Code Signing Key
+========================================
 
------BEGIN PGP PUBLIC KEY BLOCK-----
-Version: GnuPG v2.0.17 (GNU/Linux)
+The following PGP key is used to sign all releases::
 
-mQELBEGD1j0BCADHxPJkPcjJE+4Dlisx2hVc0Dj6JI1MSLrkM8R+2bOhVUSferxP
-T1EMPhfrAdOHTAloyvRThJztnZsNKqfLL49GGcBLdEGAVNks1pG37Teze5Lx1XIu
-zJFrozL2sqBy5C6nHpFgd1tcD68Rah2wp0u2cR9owXf1IqKdEfuo661+MTv7wTB1
-4hKV75nB7ZO6676SEZRILYM+7RJwKAKEmEPJc6hEf94VXn9ecNzaTlHgYkjhz9db
-LOd3od9XvuUw+LMR1dwBqMxbvR90MiXjbedDEkbArcZB9YOAIvEX/lC3qaW4XJt4
-iwHWl/YVZEfALcvQywe2CDrH5hO794wd9MpBAAYptBZCb3RhbiBEaXN0cmlidXRp
-b24gS2V5iQEqBBMBAgAUAhsDAh4BAheABQJKfFpnBBUKCQgACgkQYhHr8e+637xk
-PQf/aOi78XenwwvFrwXOVIVTdZIf8rK1zJksf26h09UD8uVV6z5iiTcpn86+eN9p
-6Ar8IH3tD+JuFnPSwZ/r9MNC2XZwenYo4Gb14jqM6/9hBe328vmeM4Y1G7bD4HrL
-kgV5WEyokqm3zbp3FBLr3Vh68TAC5JB9aHevra+cCA2u3vBNI3YUM5z4TdO150P3
-J00whkqImQEUni8bgxvllBLFM+uhucsX3HZWkoDEpotbg8yd0bqMkiPEyMr1OnJq
-eDVDMrB5wnyLgLFfRAAw3mopM0C1PNOAHr/BIYiaDHX2OwnOfep8rMDoRVf2Ge0D
-DBgsJJ6LduQHLeg403SHWL2F6YkCHAQTAQIABgUCQYPWUgAKCRBcD5boTsFta+r9
-EACWVis7YcaGkKKgRB/5ox8rM36XVhMXdh/hnnGHt5rapbbRRkRHRcWU8WIcFO1A
-59+TfwNNd8gN1MEt/5aX5KHWVKHBDexJgIxm6Dm1pisYHf/dnYQPM18hmqqwNlKY
-97hFkPpHd7enrtc/SvGbQhhLXYlpwBrdMl76e9xJLnnrRQksxegGPo8cr+C9HTs1
-Lwa8zzBxyBwYBYX+0moDkDShEhuXx6mEOXrGvQanJuIvpoIwGH+62E65MbJGlwWp
-w/MAtm2jFhBIhGV0bqJCFp9zIgdNgfskBaPr0oilbuJQZqP0Iqe/6CCt4XkS51yW
-ZqxjLAFpEpvDec4PGw3witKf/koGon9X8C035+nEjLBrWy18Q91vw2USyLI+mm9d
-iMAS8pY2gomfxBO2VwYHJryZykjCYQkccRA1tHteRj4gqTObo0Ak47y5MnplTWwi
-40oP7K2cfhCRBmMioxmYES4xsHEupfRBo3xr1Jq9q0t688WTT1NXHPMPoueF9mKZ
-Cf2pa9aHsqBmWTm3sCaNQKGubCDBEUmJUyndmSatJyYM7NVYoUp6EfqMACFuTNdB
-sjKMh7aWVikQpbJDfA1BIU3lZeqgjgrghVAWkEOBfhG0IVZj+RVCJpsqoTJ8asY2
-VreArSCyr/VnLEnfuH/QpgvCiCbepo3E34DJt4SaAOO2ZohGBBARAgAGBQJMGVc1
-AAoJEKY/LL36AvvMgsoAn2G7kXd09BF7ffk1Sfh174SVrvM9AKC7+R7x0+yV3SCd
-JkkUOo3xR5cOxw==
-=1QuR
------END PGP PUBLIC KEY BLOCK-----
+  pub   2048R/EFBADFBC 2004-10-30
+        Key fingerprint = 621D AF64 11E1 851C 4CF9  A2E1 6211 EBF1 EFBA DFBC
+  uid                  Botan Distribution Key
+
+  -----BEGIN PGP PUBLIC KEY BLOCK-----
+  Version: GnuPG v2.0.17 (GNU/Linux)
+
+  mQELBEGD1j0BCADHxPJkPcjJE+4Dlisx2hVc0Dj6JI1MSLrkM8R+2bOhVUSferxP
+  T1EMPhfrAdOHTAloyvRThJztnZsNKqfLL49GGcBLdEGAVNks1pG37Teze5Lx1XIu
+  zJFrozL2sqBy5C6nHpFgd1tcD68Rah2wp0u2cR9owXf1IqKdEfuo661+MTv7wTB1
+  4hKV75nB7ZO6676SEZRILYM+7RJwKAKEmEPJc6hEf94VXn9ecNzaTlHgYkjhz9db
+  LOd3od9XvuUw+LMR1dwBqMxbvR90MiXjbedDEkbArcZB9YOAIvEX/lC3qaW4XJt4
+  iwHWl/YVZEfALcvQywe2CDrH5hO794wd9MpBAAYptBZCb3RhbiBEaXN0cmlidXRp
+  b24gS2V5iQEqBBMBAgAUAhsDAh4BAheABQJKfFpnBBUKCQgACgkQYhHr8e+637xk
+  PQf/aOi78XenwwvFrwXOVIVTdZIf8rK1zJksf26h09UD8uVV6z5iiTcpn86+eN9p
+  6Ar8IH3tD+JuFnPSwZ/r9MNC2XZwenYo4Gb14jqM6/9hBe328vmeM4Y1G7bD4HrL
+  kgV5WEyokqm3zbp3FBLr3Vh68TAC5JB9aHevra+cCA2u3vBNI3YUM5z4TdO150P3
+  J00whkqImQEUni8bgxvllBLFM+uhucsX3HZWkoDEpotbg8yd0bqMkiPEyMr1OnJq
+  eDVDMrB5wnyLgLFfRAAw3mopM0C1PNOAHr/BIYiaDHX2OwnOfep8rMDoRVf2Ge0D
+  DBgsJJ6LduQHLeg403SHWL2F6YkCHAQTAQIABgUCQYPWUgAKCRBcD5boTsFta+r9
+  EACWVis7YcaGkKKgRB/5ox8rM36XVhMXdh/hnnGHt5rapbbRRkRHRcWU8WIcFO1A
+  59+TfwNNd8gN1MEt/5aX5KHWVKHBDexJgIxm6Dm1pisYHf/dnYQPM18hmqqwNlKY
+  97hFkPpHd7enrtc/SvGbQhhLXYlpwBrdMl76e9xJLnnrRQksxegGPo8cr+C9HTs1
+  Lwa8zzBxyBwYBYX+0moDkDShEhuXx6mEOXrGvQanJuIvpoIwGH+62E65MbJGlwWp
+  w/MAtm2jFhBIhGV0bqJCFp9zIgdNgfskBaPr0oilbuJQZqP0Iqe/6CCt4XkS51yW
+  ZqxjLAFpEpvDec4PGw3witKf/koGon9X8C035+nEjLBrWy18Q91vw2USyLI+mm9d
+  iMAS8pY2gomfxBO2VwYHJryZykjCYQkccRA1tHteRj4gqTObo0Ak47y5MnplTWwi
+  40oP7K2cfhCRBmMioxmYES4xsHEupfRBo3xr1Jq9q0t688WTT1NXHPMPoueF9mKZ
+  Cf2pa9aHsqBmWTm3sCaNQKGubCDBEUmJUyndmSatJyYM7NVYoUp6EfqMACFuTNdB
+  sjKMh7aWVikQpbJDfA1BIU3lZeqgjgrghVAWkEOBfhG0IVZj+RVCJpsqoTJ8asY2
+  VreArSCyr/VnLEnfuH/QpgvCiCbepo3E34DJt4SaAOO2ZohGBBARAgAGBQJMGVc1
+  AAoJEKY/LL36AvvMgsoAn2G7kXd09BF7ffk1Sfh174SVrvM9AKC7+R7x0+yV3SCd
+  JkkUOo3xR5cOxw==
+  =1QuR
+  -----END PGP PUBLIC KEY BLOCK-----
diff --git a/doc/pubkey.txt b/doc/pubkey.txt
new file mode 100644
index 000000000..2b765cc10
--- /dev/null
+++ b/doc/pubkey.txt
@@ -0,0 +1,398 @@
+
+.. _public_key_crypto:
+
+Public Key Cryptography
+=================================
+
+Quick Start
+---------------------------------
+
+Let's create a 2048-bit RSA private key, serialize the public key as a
+PKCS #1 file with PEM encoding (which can be understood by many other
+cryptographic programs), and then load it on another machine::
+
+  // everyone does:
+  AutoSeeded_RNG rng;
+
+  // Alice
+  RSA_PrivateKey priv_rsa(rng, 2048 /* bits */);
+
+  std::string alice_pem = X509::PEM_encode(priv_rsa);
+
+  // send alice_pem to Bob, who does
+
+  // Bob
+  std::auto_ptr<Public_Key> alice(load_key(alice_pem));
+
+  RSA_PublicKey* alice_rsa = dynamic_cast<RSA_PublicKey>(alice);
+  if(alice_rsa)
+     {
+     /* ... */
+     }
+
+Creating New Public Key Pairs
+---------------------------------
+
+The library has interfaces for public key encryption, signatures, and
+key agreement that do not require knowing the exact algorithm in
+use. One place where we *do* need to know exactly what kind of
+algorithm is in use is when we are creating a key.
+
+There are currently three kinds of public key algorithms in Botan:
+ones based on integer factorization (RSA and Rabin-Williams), ones
+based on the discrete logarithm problem in the integers modulo a prime
+(DSA, Diffie-Hellman, Nyberg-Rueppel, and ElGamal), and ones based on
+the discrete logarithm problem in an elliptic curve (ECDSA, ECDH, and
+GOST 34.10). The systems based on discrete logarithms (in either
+regular integers or elliptic curves) use a group (a mathematical
+term), which can be shared among many keys. An elliptic curve group is
+represented by the class ``EC_Domain_Params``, while a modulo-prime
+group is represented by a ``DL_Group``.
+
+There are two ways to create a DL private key (such as
+``DSA_PrivateKey``). One is to pass in just a ``DL_Group`` object -- a
+new key will automatically be generated. The other involves passing in
+a group to use, along with both the public and private values (private
+value first).
+
+Since in integer factorization algorithms, the modulus used isn't
+shared by other keys, we don't use this notion. You can create a new
+key by passing in a ``size_t`` telling how long (in bits) the key
+should be, or you can copy an pre-existing key by passing in the
+appropriate parameters (primes, exponents, etc). For RSA and
+Rabin-Williams (the two IF schemes in Botan), the parameters are all
+``BigInt``: prime 1, prime 2, encryption exponent, decryption
+exponent, modulus. The last two are optional, since they can easily be
+derived from the first three.
+
+Creating a DL_Group
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are quite a few ways to get a ``DL_Group`` object. The best is
+to use the function ``get_dl_group``, which takes a string naming a
+group; it will either return that group, if it knows about it, or
+throw an exception. Names it knows about include "modp/ietf/N" where N
+is 768, 1024, 1536, 2048, 3072, 4096, 6144, and 8192 for
+Diffie-Hellman and ElGamal. DSA-style groups are named "dsa/jce/N" for
+N 512, 768, 1024, and "dsa/botan/N" for 2048 and 3072.
+
+You can also generate a new random group. This is not recommend,
+because it is quite slow, especially for safe primes.
+
+Key Checking
+---------------------------------
+
+Most public key algorithms have limitations or restrictions on their
+parameters. For example RSA requires an odd exponent, and algorithms
+based on the discrete logarithm problem need a generator $> 1$.
+
+Each low-level public key type has a function named ``check_key`` that
+takes a ``bool``. This function returns a Boolean value that declares
+whether or not the key is valid (from an algorithmic standpoint). For
+example, it will check to make sure that the prime parameters of a DSA
+key are, in fact, prime. It does not have anything to do with the
+validity of the key for any particular use, nor does it have anything
+to do with certificates that link a key (which, after all, is just
+some numbers) with a user or other entity. If ``check_key``'s argument
+is ``true``, then it does "strong" checking, which includes expensive
+operations like primality checking.
+
+Keys are always checked when they are loaded or generated, so typically there
+is no reason to use this function directly. However, you can disable or reduce
+the checks for particular cases (public keys, loaded private keys, generated
+private keys) by setting the right config toggle (see the section on the
+configuration subsystem for details).
+
+Getting a PK algorithm object
+---------------------------------
+
+The key types, like ``RSA_PrivateKey``, do not implement any kind of
+padding or encoding (which is necessary for security). To get an
+object that knows how to do padding, use the wrapper classes included
+in ``pubkey.h``. These take a key, along with a string that specifies
+what hashing and encoding method(s) to use. Examples of such strings
+are "EME1(SHA-256)" for OAEP encryption and "EMSA4(SHA-256)" for PSS
+signatures (where the message is hashed using SHA-256).
+
+Here are some basic examples (using an RSA key) to give you a feel for
+the possibilities. These examples assume ``rsakey`` is an
+``RSA_PrivateKey``, since otherwise we would not be able to create
+a decryption or signature object with it (you can create encryption or
+signature verification objects with public keys, naturally)::
+
+   // PKCS #1 v2.0 / IEEE 1363 compatible encryption
+   PK_Encryptor_EME rsa_enc_pkcs1_v2(rsakey, "EME1(SHA-1)");
+   // PKCS #1 v1.5 compatible encryption
+   PK_Encryptor_EME rsa_enc_pkcs1_v15(rsakey, "PKCS1v15")
+
+   // This object can decrypt things encrypted by rsa_
+   PK_Decryptor_EME rsa_dec_pkcs1_v2(rsakey, "EME1(SHA-1)");
+
+   // PKCS #1 v1.5 compatible signatures
+   PK_Signer rsa_sign_pkcs1_v15(rsakey, "EMSA3(MD5)");
+   PK_Verifier rsa_verify_pkcs1_v15(rsakey, "EMSA3(MD5)");
+
+   // PKCS #1 v2.1 compatible signatures
+   PK_Signer rsa_sign_pkcs1_v2(rsakey, "EMSA4(SHA-1)");
+   PK_Verifier rsa_verify_pkcs1_v2(rsakey, "EMSA4(SHA-1)");
+
+Encryption
+---------------------------------
+
+The ``PK_Encryptor`` and ``PK_Decryptor`` classes are the
+interface for encryption and decryption, respectively.
+
+Calling ``encrypt`` with a ``byte`` array, a length
+parameter, and an RNG object will return the input encrypted with
+whatever scheme is being used. Calling the similar ``decrypt``
+will perform the inverse operation. You can also do these operations
+with ``SecureVector<byte>``s. In all cases, the output is returned
+via a ``SecureVector<byte>``.
+
+If you attempt an operation with a larger size than the key can
+support (this limit varies based on the algorithm, the key size, and
+the padding method used (if any)), an exception will be thrown. You
+can call ``maximum_input_size`` to find out the maximum size
+input (in bytes) that you can safely use with any particular key.
+
+Available public key encryption algorithms in Botan are RSA and
+ElGamal. The encoding methods are EME1, denoted by "EME1(HASHNAME)",
+PKCS #1 v1.5, called "PKCS1v15" or "EME-PKCS1-v1_5", and raw encoding
+("Raw").
+
+For compatibility reasons, PKCS #1 v1.5 is recommend for use with
+ElGamal (most other implementations of ElGamal do not support any
+other encoding format). RSA can also be used with PKCS # 1 encoding,
+but because of various possible attacks, EME1 is the preferred
+encoding. EME1 requires the use of a hash function: unless a competent
+applied cryptographer tells you otherwise, you should use SHA-256 or
+SHA-512.
+
+Don't use "Raw" encoding unless you need it for backward
+compatibility with old protocols. There are many possible attacks
+against both ElGamal and RSA when they are used in this way.
+
+Signatures
+---------------------------------
+
+The signature algorithms look quite a bit like the hash functions. You
+can repeatedly call ``update``, giving more and more of a
+message you wish to sign, and then call ``signature``, which
+will return a signature for that message. If you want to do it all in
+one shot, call ``sign_message``, which will just call
+``update`` with its argument and then return whatever
+``signature`` returns. Generating a signature requires random
+numbers with some schemes, so ``signature`` and
+``sign_message`` both take a ``RandomNumberGenerator&``.
+
+You can validate a signature by updating the verifier class, and finally seeing
+the if the value returned from ``check_signature`` is true (you pass
+the supposed signature to the ``check_signature`` function as a byte
+array and a length or as a ``MemoryRegion<byte>``). There is another
+function, ``verify_message``, which takes a pair of byte array/length
+pairs (or a pair of ``MemoryRegion<byte>`` objects), the first of which is
+the message, the second being the (supposed) signature. It returns true if the
+signature is valid and false otherwise.
+
+Available public key signature algorithms in Botan are RSA, DSA,
+ECDSA, GOST-34.11, Nyberg-Rueppel, and Rabin-Williams. Signature
+encoding methods include EMSA1, EMSA2, EMSA3, EMSA4, and Raw. All of
+them, except Raw, take a parameter naming a message digest function to
+hash the message with. The Raw encoding signs the input directly; if
+the message is too big, the signing operation will fail. Raw is not
+useful except in very specialized applications.
+
+There are various interactions that make certain encoding schemes and
+signing algorithms more or less useful.
+
+EMSA2 is the usual method for encoding Rabin-William signatures, so
+for compatibility with other implementations you may have to use
+that. EMSA4 (also called PSS), also works with Rabin-Williams. EMSA1
+and EMSA3 do *not* work with Rabin-Williams.
+
+RSA can be used with any of the available encoding methods. EMSA4 is
+by far the most secure, but is not (as of now) widely
+implemented. EMSA3 (also called "EMSA-PKCS1-v1_5") is commonly used
+with RSA (for example in SSL). EMSA1 signs the message digest
+directly, without any extra padding or encoding. This may be useful,
+but is not as secure as either EMSA3 or EMSA4. EMSA2 may be used but
+is not recommended.
+
+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.
+
+Key Agreement
+---------------------------------
+
+You can get a hold of a ``PK_Key_Agreement_Scheme`` object by calling
+``get_pk_kas`` with a key that is of a type that supports key
+agreement (such as a Diffie-Hellman key stored in a ``DH_PrivateKey``
+object), and the name of a key derivation function. This can be "Raw",
+meaning the output of the primitive itself is returned as the key, or
+"KDF1(hash)" or "KDF2(hash)" where "hash" is any string you happen to
+like (hopefully you like strings like "SHA-256" or "RIPEMD-160"), or
+"X9.42-PRF(keywrap)", which uses the PRF specified in ANSI X9.42. It
+takes the name or OID of the key wrap algorithm that will be used to
+encrypt a content encryption key.
+
+How key agreement works is that you trade public values with some
+other party, and then each of you runs a computation with the other's
+value and your key (this should return the same result to both
+parties). This computation can be called by using
+``derive_key`` with either a byte array/length pair, or a
+``SecureVector<byte>`` than holds the public value of the other
+party. The last argument to either call is a number that specifies how
+long a key you want.
+
+Depending on the KDF you're using, you *might not* get back a key
+of the size you requested. In particular "Raw" will return a number
+about the size of the Diffie-Hellman modulus, and KDF1 can only return
+a key that is the same size as the output of the hash. KDF2, on the
+other hand, will always give you a key exactly as long as you request,
+regardless of the underlying hash used with it. The key returned is a
+``SymmetricKey``, ready to pass to a block cipher, MAC, or other
+symmetric algorithm.
+
+The public value that should be used can be obtained by calling
+``public_data``, which exists for any key that is associated with a
+key agreement algorithm. It returns a ``SecureVector<byte>``.
+
+"KDF2(SHA-256)" is by far the preferred algorithm for key derivation
+in new applications. The X9.42 algorithm may be useful in some
+circumstances, but unless you need X9.42 compatibility, KDF2 is easier
+to use.
+
+There is a Diffie-Hellman example included in the distribution, which you may
+want to examine.
+
+.. _pk_import_export:
+
+Importing and Exporting Keys
+---------------------------------
+
+There are many, many different (often conflicting) standards
+surrounding public key cryptography. There is, thankfully, only two
+major standards surrounding the representation of a public or private
+key: the X.509 subject public key info format (for public keys), and
+PKCS #8 (for private keys). Other crypto libraries, such as Crypto++
+and OpenSSL, also support these formats, so you can easily exchange
+keys with software that doesn't use Botan.
+
+In addition to "plain" public keys, Botan also supports X.509
+certificates.  These are documented in :ref:`x509_certificates`.
+
+.. _import_export_public_keys:
+
+Importing/Exporting Public Keys
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To import and export public keys, use:
+
+.. cpp:function:: MemoryVector<byte> X509::BER_encode(const Public_Key& key)
+
+  Takes any public key object, and returns a standard binary structure
+  representing the key which can be read by many other crypto
+  libraries.
+
+.. cpp:function:: std::string X509::PEM_encode(const Public_Key& key)
+
+  This formats the key the same as ``BER_encode``, but additionally
+  encodes it into a text format with identifying headers. Using PEM
+  encoding is *highly* recommended for many reasons, including
+  compatibility with other software, for transmission over 8-bit
+  unclean channels, because it can be identified by a human without
+  special tools, and because it sometimes allows more sane behavior of
+  tools that process the data.
+
+.. cpp:function:: Public_Key* X509::load_key(DataSource& in)
+
+.. cpp:function:: Public_Key* X509::load_key(const SecureVector<byte>& buffer)
+
+.. cpp:function:: Public_Key* X509::load_key(const std::string& filename)
+
+  For loading a public key, use one of the variants of ``load_key``.
+  This function will return a newly allocated key based on the data
+  from whatever source it is using (assuming, of course, the source is
+  in fact storing a representation of a public key). The encoding used
+  (PEM or BER) need not be specified; the format will be detected
+  automatically. The key is allocated with ``new``, and should be
+  released with ``delete`` when you are done with it. The first takes
+  a generic ``DataSource`` that 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``.
+
+Importing/Exporting Private Keys
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two different options for private key import/export. The
+first is a plaintext version of the private key. This is supported by
+the following functions:
+
+.. cpp:function:: SecureVector<byte> PKCS8::BER_encode(const Private_Key& key)
+
+.. cpp:function:: std::string PKCS8::PEM_encode(const Private_Key& key)
+
+These functions are similiar to the X.509 functions described in
+:ref:`import_export_public_keys`. The only difference is that they take
+a ``Private_Key`` object instead. In most situations, using these
+versions is a bad idea, because anyone can come along and grab the
+private key without having to know any passwords or other
+secrets. Unless you have very particular security requirements, always
+use the versions that encrypt the key based on a passphrase described
+below. For importing, the same functions can be used for encrypted and
+unencrypted keys.
+
+The other way to export a PKCS #8 key is to first encode it in the
+same manner as done above, then encrypt it using a passphrase, and
+store the whole thing into another structure. This method is
+definitely preferred, since otherwise the private key is
+unprotected. The algorithms and structures used here are standardized
+by PKCS #5 and PKCS #8, and can be read by many other crypto
+libraries:
+
+.. cpp:function:: SecureVector<byte> PKCS8::BER_encode(const Private_Key& key, RandomNumberGenerator& rng, const std::string& pass, const std::string& pbe_algo = "")
+
+.. cpp:function:: std::string PKCS8::PEM_encode(const Private_Key& key, RandomNumberGenerator& rng, const std::string& pass, const std::string& pbe_algo = "")
+
+
+There are three new arguments needed here to support the encryption
+process. The first is a ``RandomNumberGenerator``, which is used to
+generate salts to randomize the encryption. The ``pass`` argument is
+the passphrase that will be used to encrypt the key. Both of these are
+required. The final (optional) argument, ``pbe_algo``, specifies a
+particular password based encryption (or PBE) algorithm. If you don't
+specify a PBE, a sensible default will be used.
+
+Last but not least, there are some functions that will load (and
+decrypt, if necessary) a PKCS #8 private key:
+
+.. cpp:function:: Private_Key* PKCS8::load_key(DataSource& in, RandomNumberGenerator& rng, const User_Interface& ui)
+
+.. cpp:function:: Private_Key* PKCS8::load_key(DataSource& in, RandomNumberGenerator& rng, std::string passphrase = "")
+
+.. cpp:function:: Private_Key* PKCS8::load_key(const std::string& filename, RandomNumberGenerator& rng, const User_Interface& ui)
+
+.. cpp:function:: Private_Key* PKCS8::load_key(const std::string& filename, RandomNumberGenerator& rng, const std::string& passphrase = "")
+
+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.
+
+All versions need access to a ``RandomNumberGenerator`` in order to
+perform probabilistic tests on the loaded key material.
+
+After loading a key, you can use ``dynamic_cast`` to find out what
+operations it supports, and use it appropriately. Remember to
+``delete`` the object once you are done with it.
diff --git a/doc/python.tex b/doc/python.tex
deleted file mode 100644
index afdd66b6a..000000000
--- a/doc/python.tex
+++ /dev/null
@@ -1,68 +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 Python Interface Documentation}}
-\author{Jack Lloyd \\
-        \texttt{[email protected]}}
-\date{2009/10/10}
-
-\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{Ciphers}
-
-Botan's Python interface provides a generic interface to any cipher
-supported by the library. The class \type{botan.Cipher} takes three
-arguments, all strings: first, the name of the algorith, second the
-direction (which can be either ``encrypt'' or ``decrypt''), and
-lastly, the key to use. For instance
-
-\begin{verbatim}
-    encryptor = botan.Cipher("AES-128/EAX", "encrypt", key)
-\end{verbatim}
-
-creates an object that will encrypt and authenticate messages using
-the EAX mode of operation using the AES cipher. To use this object,
-call the \function{cipher} function with two arguments - the input
-to encrypt, and the IV to use:
-
-\begin{verbatim}
-    ciphertext = encryptor.cipher(input, salt)
-\end{verbatim}
-
-
-\subsection{Cryptobox}
-
-
-\subsection{RNGs}
-
-\section{RSA}
-
-
-
-\end{document}
diff --git a/doc/scripts/print_deps.py b/doc/scripts/print_deps.py
deleted file mode 100755
index c68fa2617..000000000
--- a/doc/scripts/print_deps.py
+++ /dev/null
@@ -1,70 +0,0 @@
-#!/usr/bin/python
-
-"""
-Analyze the botan source tree and print the module interdependencies
-
-(C) 2009 Jack Lloyd
-Distributed under the terms of the Botan license
-"""
-
-import os
-import os.path
-import sys
-import re
-
-def find_deps_in(filename):
-    # By convention #include's with spaces before them are
-    # always wrapped in #ifdef blocks
-    regexp = re.compile('^#include <botan/(.*)>')
-
-    for line in open(filename).readlines():
-        match = regexp.match(line)
-        if match != None:
-            yield match.group(1).replace('internal/', '')
-
-def get_dependencies(dirname):
-    all_dirdeps = {}
-    file_homes = {}
-
-    is_sourcefile = re.compile('\.(cpp|h|S)$')
-
-    for (dirpath, dirnames, filenames) in os.walk('src'):
-        dirdeps = set()
-        for filename in filenames:
-            if is_sourcefile.search(filename) != None:
-                file_homes[filename] = os.path.basename(dirpath)
-
-                for dep in find_deps_in(os.path.join(dirpath, filename)):
-                    if dep not in filenames and dep != 'build.h':
-                        dirdeps.add(dep)
-
-        dirdeps = sorted(dirdeps)
-        if dirdeps != []:
-            all_dirdeps[dirpath] = dirdeps
-
-    return (all_dirdeps, file_homes)
-
-def main():
-    (all_dirdeps, file_homes) = get_dependencies('src')
-
-    def interesting_dep_for(dirname):
-        def interesting_dep(dep):
-            if dep == 'utils':
-                return False # everything depends on it
-
-            # block/serpent depends on block, etc
-            if dirname.find('/%s/' % (dep)) > 0:
-                return False
-            return True
-        return interesting_dep
-
-    for dirname in sorted(all_dirdeps.keys()):
-        depdirs = sorted(set(map(lambda x: file_homes[x], all_dirdeps[dirname])))
-
-        depdirs = filter(interesting_dep_for(dirname), depdirs)
-
-        if depdirs != []:
-            print "%s: %s" % (dirname, ' '.join(depdirs))
-
-if __name__ == '__main__':
-    sys.exit(main())
diff --git a/doc/scripts/update_deps.py b/doc/scripts/update_deps.py
deleted file mode 100755
index ac19885e0..000000000
--- a/doc/scripts/update_deps.py
+++ /dev/null
@@ -1,41 +0,0 @@
-#!/usr/bin/python
-
-import sys
-import re
-import os.path
-
-def update_requires(dir, deps):
-    lines = map(lambda x: x.strip(),
-                open(os.path.join(dir, 'info.txt')).readlines())
-
-    if '<requires>' in lines:
-        start = lines.index('<requires>')
-
-        while lines.pop(start) != '</requires>':
-            pass
-
-    while len(lines) > 0 and lines[-1] == '':
-        lines = lines[:-1]
-
-    if len(deps) > 0:
-        lines.append('')
-        lines.append('<requires>')
-        for dep in deps:
-            lines.append(dep)
-        lines.append('</requires>')
-        lines.append('')
-
-    lines = "\n".join(lines).replace("\n\n\n", "\n\n")
-
-    output = open(os.path.join(dir, 'info.txt'), 'w')
-    output.write(lines)
-    output.close()
-
-def main():
-    for line in sys.stdin.readlines():
-        (dirname, deps) = line.split(':')
-        deps = deps.strip().split(' ')
-        update_requires(dirname, deps)
-
-if __name__ == '__main__':
-    sys.exit(main())
diff --git a/doc/thanks.txt b/doc/thanks.txt
deleted file mode 100644
index 68fd81b3b..000000000
--- a/doc/thanks.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-
-The following people (sorted alphabetically) contributed bug reports, useful
-information, or were generally just helpful people to talk to:
-
-Jeff B
-Rickard Bondesson
-Mike Desjardins
-Matthew Gregan
-Hany Greiss
-Friedemann Kleint
-Ying-Chieh Liao
-Dan Nicolaescu
-Vaclav Ovsik
-Ken Perano
-Darren Starsmore
-Kaushik Veeraraghavan
-Dominik Vogt
-James Widener
-
-Cerulean Studios, creators of the Trillian instant messaging client,
-has provided financial assistance to the project.
-
-Barry Kavanagh of AEP Systems Ltd kindly provided an AEP2000 crypto card and
-drivers, enabling the creation of Botan's AEP engine module.
-
-In addition, the following people have unknowingly contributed help
-via public domain code which has been repurposed into the library:
-
-  Dean Gaudet wrote the SSE2 implementation of SHA-1
-
-  Mike Hamburg wrote x86-64/SSSE3 assembly which was the basis for the
-  constant time AES implementation
-
-  The implementation of DES is based off a public domain implementation by Phil
-  Karn from 1994 (he, in turn, credits Richard Outerbridge and Jim Gillogly).
-
-  Rijndael and Square are based on the reference implementations written by
-  the inventors, Joan Daemen and Vincent Rijmen.
-
-  The Serpent S-boxes used were discovered by Dag Arne Osvik and detailed in
-  his paper "Speeding Up Serpent".
-
-  Matthew Skala's public domain twofish.c (as given in GnuPG 0.9.8) provided
-  the basis for my Twofish code (particularly the key schedule).
-
-  Some of the hash functions (MD5, SHA-1, etc) use an optimized implementation
-  of one of the boolean functions, which was discovered by Colin Plumb.
-
-  The design of Randpool takes some of its design principles from those
-  suggested by Eric A. Young in his SSLeay documentation, Peter Gutmann's paper
-  "Software Generation of Practically Strong Random Numbers", and the paper
-  "Cryptanalytic Attacks on Pseudorandom Number Generators", by Kelsey,
-  Schneier, Wagner, and Hall.
diff --git a/doc/x509.txt b/doc/x509.txt
new file mode 100644
index 000000000..3243928de
--- /dev/null
+++ b/doc/x509.txt
@@ -0,0 +1,543 @@
+
+.. _x509_certificates:
+
+Certificate Handling
+=================================
+
+A certificate is a binding between some identifying information
+(called a *subject*) and a public key. This binding is asserted
+by a signature on the certificate, which is placed there by some
+authority (the *issuer*) that at least claims that it knows the
+subject named in the certificate really "owns" the private key
+corresponding to the public key in the certificate.
+
+The major certificate format in use today is X.509v3, designed by ISO and
+further hacked on by dozens (hundreds?) of other organizations.
+
+When working with certificates, the main class to remember is
+``X509_Certificate``. You can read an object of this type, but you
+can't create one on the fly; a CA object is necessary for making a new
+certificate. So for the most part, you only have to worry about
+reading them in, verifying the signatures, and getting the bits of
+data in them (most commonly the public key, and the information about
+the user of that key). An X.509v3 certificate can contain a literally
+infinite number of items related to all kinds of things. Botan doesn't
+support a lot of them, because nobody uses them and they're an
+impossible mess to work with. This section only documents the most
+commonly used ones of the ones that are supported; for the rest, read
+``x509cert.h`` and ``asn1_obj.h`` (which has the
+definitions of various common ASN.1 constructs used in X.509).
+
+So what's in an X.509 certificate?
+-----------------------------------
+
+Obviously, you want to be able to get the public key. This is achieved
+by calling the member function ``subject_public_key``, which
+will return a ``Public_Key*``. As to what to do with this, read
+about ``load_key`` in the section ``Importing and Exporting PK
+Keys''. In the general case, this could be any kind of public key,
+though 99% of the time it will be an RSA key. However, Diffie-Hellman
+and DSA keys are also supported, so be careful about how you treat
+this. It is also a wise idea to examine the value returned by
+``constraints``, to see what uses the public key is approved
+for.
+
+The second major piece of information you'll want is the
+name/email/etc of the person to whom this certificate is
+assigned. Here is where things get a little nasty. X.509v3 has two
+(well, mostly just two $...$) different places where you can stick
+information about the user: the *subject* field, and in an
+extension called *subjectAlternativeName*. The *subject*
+field is supposed to only included the following information: country,
+organization, an organizational sub-unit name, and a so-called common
+name. The common name is usually the name of the person, or it could
+be a title associated with a position of some sort in the
+organization. It may also include fields for state/province and
+locality. What a locality is, nobody knows, but it's usually given as
+a city name.
+
+Botan doesn't currently support any of the Unicode variants used in
+ASN.1 (UTF-8, UCS-2, and UCS-4), any of which could be used for the
+fields in the DN. This could be problematic, particularly in Asia and
+other areas where non-ASCII characters are needed for most names. The
+UTF-8 and UCS-2 string types *are* accepted (in fact, UTF-8 is
+used when encoding much of the time), but if any of the characters
+included in the string are not in ISO 8859-1 (ie 0 ... 255), an
+exception will get thrown. Currently the ``ASN1_String`` type
+holds its data as ISO 8859-1 internally (regardless of local character
+set); this would have to be changed to hold UCS-2 or UCS-4 in order to
+support Unicode (also, many interfaces in the X.509 code would have to
+accept or return a ``std::wstring`` instead of a
+``std::string``).
+
+Like the distinguished names, subject alternative names can contain a
+lot of things that Botan will flat out ignore (most of which you would
+likely never want to use). However, there are three very useful pieces
+of information that this extension might hold: an email address
+([email protected]), a DNS name (somehost.example.com), or a URI
+(http://www.example.com).
+
+So, how to get the information? Call ``subject_info`` with the
+name of the piece of information you want, and it will return a
+``std::string`` that is either empty (signifying that the
+certificate doesn't have this information), or has the information
+requested. There are several names for each possible item, but the
+most easily readable ones are: "Name", "Country",
+"Organization", ``Organizational Unit'', "Locality", "State",
+"RFC822", "URI", and "DNS". These values are returned as a
+``std::string``.
+
+You can also get information about the issuer of the certificate in the same
+way, using ``issuer_info``.
+
+X.509v3 Extensions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+X.509v3 specifies a large number of possible extensions. Botan
+supports some, but by no means all of them. This section lists which
+ones are supported, and notes areas where there may be problems with
+the handling.
+
+ - Key Usage and Extended Key Usage: No problems known.
+
+ - Basic Constraints: No problems known. The default for a v1/v2
+   certificate is assume it's a CA if and only if the option
+   "x509/default_to_ca" is set. A v3 certificate is marked as a CA if
+   (and only if) the basic constraints extension is present and set
+   for a CA cert.
+
+ - Subject Alternative Names: Only the "rfc822Name", "dNSName", and
+   "uniformResourceIdentifier" fields will be stored; all others are
+   ignored.
+
+ - Issuer Alternative Names: Same restrictions as the Subject
+   Alternative Names extension. New certificates generated by Botan
+   never include the issuer alternative name.
+
+ - Authority Key Identifier: Only the version using KeyIdentifier is
+   supported. If the GeneralNames version is used and the extension is
+   critical, an exception is thrown. If both the KeyIdentifier and
+   GeneralNames versions are present, then the KeyIdentifier will be
+   used, and the GeneralNames ignored.
+
+ - Subject Key Identifier: No problems known.
+
+Revocation Lists
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It will occasionally happen that a certificate must be revoked before
+its expiration date. Examples of this happening include the private
+key being compromised, or the user to which it has been assigned
+leaving an organization. Certificate revocation lists are an answer to
+this problem (though online certificate validation techniques are
+starting to become somewhat more popular). Every once in a while the
+CA will release a new CRL, listing all certificates that have been
+revoked. Also included is various pieces of information like what time
+a particular certificate was revoked, and for what reason. In most
+systems, it is wise to support some form of certificate revocation,
+and CRLs handle this easily.
+
+For most users, processing a CRL is quite easy. All you have to do is call the
+constructor, which will take a filename (or a ``DataSource&``). The CRLs
+can either be in raw BER/DER, or in PEM format; the constructor will figure out
+which format without any extra information. For example::
+
+   X509_CRL crl1("crl1.der");
+
+   DataSource_Stream in("crl2.pem");
+   X509_CRL crl2(in);
+
+After that, pass the ``X509_CRL`` object to a ``X509_Store`` object
+with ``X509_Code`` ``add_crl``(``X509_CRL``), and all future
+verifications will take into account the certificates listed, assuming
+``add_crl`` returns ``VERIFIED``. If it doesn't return
+``VERIFIED``, then the return value is an error code signifying that the CRL
+could not be processed due to some problem (which could range from the issuing
+certificate not being found, to the CRL having some format problem). For more
+about the ``X509_Store`` API, read the section later in this chapter.
+
+Reading Certificates
+---------------------------------
+
+``X509_Certificate`` has two constructors, each of which takes a source of
+data; a filename to read, and a ``DataSource&``.
+
+Storing and Using Certificates
+---------------------------------
+
+If you read a certificate, you probably want to verify the signature on
+it. However, consider that to do so, we may have to verify the signature on the
+certificate that we used to verify the first certificate, and on and on until
+we hit the top of the certificate tree somewhere. It would be a might huge pain
+to have to handle all of that manually in every application, so there is
+something that does it for you: ``X509_Store``.
+
+The basic operations are: put certificates and CRLs into it, search
+for certificates, and attempt to verify certificates. That's about
+it. In the future, there will be support for online retrieval of
+certificates and CRLs (eg with the HTTP cert-store interface
+currently under consideration by PKIX).
+
+Adding Certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can add new certificates to a certificate store using any of these
+functions:
+
+``add_cert``(``const X509_Certificate&`` ``cert``,
+                     ``bool`` ``trusted`` ``= false``)
+
+``add_certs``(``DataSource&`` ``source``)
+
+``add_trusted_certs``(``DataSource&`` ``source``)
+
+The versions that take a ``DataSource&`` will add all the certificates
+that it can find in that source.
+
+All of them add the cert(s) to the store. The 'trusted' certificates are the
+ones that you have some reason to trust are genuine. For example, say your
+application is working with certificates that are owned by employees of some
+company, and all of their certificates are signed by the company CA, whose
+certificate is in turned signed by a commercial root CA. What you would then do
+is include the certificate of the commercial CA with your application, and read
+it in as a trusted certificate. From there, you could verify the company CA's
+certificate, and then use that to verify the end user's certificates. Only
+self-signed certificates may be considered trusted.
+
+Adding CRLs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``X509_Code`` ``add_crl``(``const X509_CRL&`` ``crl``);
+
+This will process the CRL and mark the revoked certificates. This will also
+work if a revoked certificate is added to the store sometime after the CRL is
+processed. The function can return an error code (listed later), or will return
+``VERIFIED`` if everything completed successfully.
+
+Storing Certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can output a set of certificates by calling ``PEM_encode``, which
+will return a ``std::string`` containing each of the certificates in the
+store, PEM encoded and concatenated. This simple format can easily be read by
+both Botan and other libraries/applications.
+
+Searching for Certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can find certificates in the store with a series of functions contained
+in the ``X509_Store_Search`` namespace::
+
+  std::vector<X509_Certificate> by_email(const X509_Store& store,
+                                         const std::string& email_addr);
+  std::vector<X509_Certificate> by_name(const X509_Store& store,
+                                        const std::string& name);
+  std::vector<X509_Certificate> by_dns(const X509_Store&,
+                                       const std::string& dns_name);
+
+These functions will return a (possibly empty) vector of certificates from
+``store`` matching your search criteria. The email address and DNS name
+searches are case-insensitive but are sensitive to extra whitespace and so
+on. The name search will do case-insensitive substring matching, so, for
+example, calling ``X509_Store_Search::by_name``(``your_store``,
+"dob") will return certificates for ``J.R. 'Bob' Dobbs'' and
+``H. Dobbertin'', assuming both of those certificates are in ``your_store``.
+
+You could then display the results to a user, and allow them to select the
+appropriate one. Searching using an email address as the key is usually more
+effective than the name, since email addresses are rarely shared.
+
+Certificate Stores
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An object of type ``Certificate_Store`` is a generalized interface
+to an external source for certificates (and CRLs). Examples of such a
+store would be one that looked up the certificates in a SQL database,
+or by contacting a CGI script running on a HTTP server. There are
+currently three mechanisms for looking up a certificate, and one for
+retrieving CRLs. By default, most of these mechanisms will return an
+empty ``std::vector`` of ``X509_Certificate``. This storage
+mechanism is *only* queried when doing certificate validation: it
+allows you to distribute only the root key with an application, and
+let some online method handle getting all the other certificates that
+are needed to validate an end entity certificate. In particular, the
+search routines will not attempt to access the external database.
+
+The three certificate lookup methods are ``by_SKID`` (Subject Key
+Identifier), ``by_name`` (the CommonName DN entry), and
+``by_email`` (stored in either the distinguished name, or in a
+subjectAlternativeName extension). The name and email versions take a
+``std::string``, while the SKID version takes a ``SecureVector<byte>``
+containing the subject key identifier in raw binary. You can choose not to
+implement ``by_name`` or ``by_email``, but ``by_SKID``
+is mandatory to implement, and, currently, is the only version that is used by
+``X509_Store``.
+
+Finally, there is a method for finding CRLs, called
+``get_crls_for``, that takes an ``X509_Certificate``
+object, and returns a ``std::vector`` of ``X509_CRL``. While
+normally there will be only one CRL, the use of the vector makes it
+easy to return no CRLs (eg, if the certificate store doesn't support
+retrieving them), or return multiple ones (for example, if the
+certificate store can't determine precisely which key was used to sign
+the certificate). Implementing the function is optional, and by
+default will return no CRLs. If it is available, it will be used by
+``X509_CRL``.
+
+As for using such a store, you have to tell ``X509_Store`` about
+it, by calling the ``X509_Store`` member function
+
+``add_new_certstore``(``Certificate_Store``* ``new_store``)
+
+The argument, ``new_store``, will be deleted by ``X509_Store``'s
+destructor, so make sure to allocate it with ``new``.
+
+Verifying Certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is a single function in ``X509_Store`` related to verifying a
+certificate:
+
+.. .cpp:function:: X509_Code validate_cert(const X509_Certificate& cert, Cert_Usage usage = ANY)
+
+This function will return ``VERIFIED`` if the certificate can
+safely be considered valid for the usage(s) described by ``usage``,
+and an error code if it is not. Naturally, things are a bit more
+complicated than that. The enum ``Cert_Usage`` is defined inside
+the ``X509_Store`` class, it (currently) can take on any of the
+values ``ANY`` (any usage is OK), ``TLS_SERVER`` (for SSL/TLS
+server authentication), ``TLS_CLIENT`` (for SSL/TLS client
+authentication), ``CODE_SIGNING``, ``EMAIL_PROTECTION`` (email
+encryption, usually this means S/MIME), ``TIME_STAMPING`` (in
+theory any time stamp application, usually IETF PKIX's Time Stamp
+Protocol), or ``CRL_SIGNING``. Note that Microsoft's code signing
+system, certainly the most widely used, uses a completely different
+(and mostly undocumented) method for marking certificates for code
+signing.
+
+First, how does it know if a certificate is valid? A certificate is
+valid if both of the following hold: a) the signature in the
+certificate can be verified using the public key in the issuer's
+certificate, and b) the issuer's certificate is a valid CA
+certificate. Note that this definition is recursive. We get out of
+this by "bottoming out" when we reach a certificate that we consider
+trusted. In general this will either be a commercial root CA, or an
+organization or application specific CA.
+
+There are a few other restrictions (validity periods, key usage
+restrictions, etc), but the above summarizes the major points of the
+validation algorithm. In theory, Botan implements the certificate path
+validation algorithm given in RFC 2459, but in practice it does not
+(yet), because we don't support the X.509v3 policy or name constraint
+extensions.
+
+Possible values for ``usage`` are ``TLS_SERVER``, ``TLS_CLIENT``,
+``CODE_SIGNING``, ``EMAIL_PROTECTION``, ``CRL_SIGNING``, and
+``TIME_STAMPING``, and ``ANY``. The default ``ANY`` does not mean
+valid for any use, it means "is valid for some usage". This is usually
+what you want; requiring that a random certificate support a
+particular usage will likely result in a lot of failures, unless your
+application is very careful to always issue certificates with the
+proper extensions, and you never use certificates generated by other
+apps.
+
+Return values for ``validate_cert`` (and ``add_crl``) include:
+
+ - VERIFIED: The certificate is valid for the specified use.
+
+ - INVALID_USAGE: The certificate cannot be used for the specified use.
+
+ - CANNOT_ESTABLISH_TRUST: The root certificate was not marked as
+   trusted.
+
+ - CERT_CHAIN_TOO_LONG: The certificate chain exceeded the length
+   allowed by a basicConstraints extension.
+
+ - SIGNATURE_ERROR: An invalid signature was found
+
+ - POLICY_ERROR: Some problem with the certificate policies was found.
+
+ - CERT_FORMAT_ERROR: Some format problem was found in a certificate.
+ - CERT_ISSUER_NOT_FOUND: The issuer of a certificate could not be found.
+ - CERT_NOT_YET_VALID: The certificate is not yet valid.
+ - CERT_HAS_EXPIRED: The certificate has expired.
+ - CERT_IS_REVOKED: The certificate has been revoked.
+ - CRL_FORMAT_ERROR: Some format problem was found in a CRL.
+ - CRL_ISSUER_NOT_FOUND: The issuer of a CRL could not be found.
+ - CRL_NOT_YET_VALID: The CRL is not yet valid.
+ - CRL_HAS_EXPIRED: The CRL has expired.
+ - CA_CERT_CANNOT_SIGN: The CA certificate found does not have an
+   contain a public key that allows signature verification.
+ - CA_CERT_NOT_FOR_CERT_ISSUER: The CA cert found is not allowed to
+   issue certificates.
+ - CA_CERT_NOT_FOR_CRL_ISSUER: The CA cert found is not allowed to
+   issue CRLs.
+ - UNKNOWN_X509_ERROR: Some other error occurred.
+
+Certificate Authorities
+---------------------------------
+
+Setting up a CA for X.509 certificates is perhaps the easiest thing to
+do related to X.509. A CA is represented by the type ``X509_CA``,
+which can be found in ``x509_ca.h``. A CA always needs its own
+certificate, which can either be a self-signed certificate (see below
+on how to create one) or one issued by another CA (see the section on
+PKCS #10 requests). Creating a CA object is done by the following
+constructor::
+
+   X509_CA(const X509_Certificate& cert, const Private_Key& key);
+
+The private key is the private key corresponding to the public key in the
+CA's certificate.
+
+Requests for new certificates are supplied to a CA in the form on PKCS
+#10 certificate requests (called a ``PKCS10_Request`` object in
+Botan). These are decoded in a similar manner to
+certificates/CRLs/etc. A request is vetted by humans (who somehow
+verify that the name in the request corresponds to the name of the
+entity who requested it), and then signed by a CA key, generating a
+new certificate::
+
+   X509_Certificate sign_request(const PKCS10_Request&) const;
+
+Generating CRLs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As mentioned previously, the ability to process CRLs is highly important in
+many PKI systems. In fact, according to strict X.509 rules, you must not
+validate any certificate if the appropriate CRLs are not available (though
+hardly any systems are that strict). In any case, a CA should have a valid CRL
+available at all times.
+
+Of course, you might be wondering what to do if no certificates have
+been revoked. Never fear; empty CRLs, which revoke nothing at all, can
+be issued. To generate a new, empty CRL, just call ``X509_CRL``
+``X509_CA::new_crl``(``size_t``~``seconds``~=~0)~--~it
+will create a new, empty, CRL. If ``seconds`` is the default 0, then
+the normal default CRL next update time (the value of the
+``x509/crl/next_update'') will be used. If not, then ``seconds``
+specifies how long (in seconds) it will be until the CRL's next update
+time (after this time, most clients will reject the CRL as too old).
+
+On the other hand, you may have issued a CRL before. In that case, you will
+want to issue a new CRL that contains all previously revoked
+certificates, along with any new ones. This is done by calling the
+``X509_CA`` member function
+``update_crl``(``X509_CRL``~``old_crl``,
+``std::vector<CRL_Entry>``~``new_revoked``,
+``size_t``~``seconds``~=~0), where ``X509_CRL`` is the last CRL this
+CA issued, and ``new_revoked`` is a list of any newly revoked certificates.
+The function returns a new ``X509_CRL`` to make available for clients. The
+semantics for the ``seconds`` argument is the same as ``new_crl``.
+
+The ``CRL_Entry`` type is a structure that contains, at a minimum, the
+serial number of the revoked certificate. As serial numbers are never repeated,
+the pairing of an issuer and a serial number (should) distinctly identify any
+certificate. In this case, we represent the serial number as a
+``SecureVector<byte>`` called ``serial``. There are two additional
+(optional) values, an enumeration called ``CRL_Code`` that specifies the
+reason for revocation (``reason``), and an object that represents the time
+that the certificate became invalid (if this information is known).
+
+If you wish to remove an old entry from the CRL, insert a new entry for the
+same cert, with a ``reason`` code of ``DELETE_CRL_ENTRY``. For example,
+if a revoked certificate has expired 'normally', there is no reason to continue
+to explicitly revoke it, since clients will reject the cert as expired in any
+case.
+
+Self-Signed Certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Generating a new self-signed certificate can often be useful, for
+example when setting up a new root CA, or for use in email
+applications. The library provides a utility function for this::
+
+.. cpp:function:: X509_Certificate create_self_signed_cert(const X509_Cert_Options& opts, const Private_Key& key)
+
+Where ``key`` is obviously the private key you wish to use (the public key,
+used in the certificate itself, is extracted from the private key), and
+``opts`` is an structure that has various bits of information that will be
+used in creating the certificate (this structure, and its use, is discussed
+below). This function is found in the header ``x509self.h``. There is an
+example of using this function in the ``self_sig`` example.
+
+Creating PKCS #10 Requests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Also in ``x509self.h``, there is a function for generating new PKCS #10
+certificate requests::
+
+.. cpp:function:: PKCS10_Request create_cert_req(const X509_Cert_Options&, const Private_Key&)
+
+This function acts quite similarly to ``create_self_signed_cert``,
+except it instead returns a PKCS #10 certificate request. After creating it,
+one would typically transmit it to a CA, who signs it and returns a freshly
+minted X.509 certificate. There is an example of using this function in the
+``pkcs10`` example.
+
+Certificate Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+What is this ``X509_Cert_Options`` thing we've been passing
+around? It's a class representing a bunch of information that will end
+up being stored into the certificate. This information comes in 3
+major flavors: information about the subject (CA or end-user), the
+validity period of the certificate, and restrictions on the usage of
+the certificate.
+
+First and foremost is a number of ``std::string`` members, which contains
+various bits of information about the user: ``common_name``,
+``serial_number``, ``country``, ``organization``, ``org_unit``,
+``locality``, ``state``, ``email``, ``dns_name``, and ``uri``. As
+many of these as possible should be filled it (especially an email address),
+though the only required ones are ``common_name`` and ``country``.
+
+There is another value that is only useful when creating a PKCS #10 request,
+which is called ``challenge``. This is a challenge password, which you can
+later use to request certificate revocation (*if* the CA supports doing
+revocations in this manner).
+
+Then there is the validity period; these are set with ``not_before``
+and ``not_after``. Both of these functions also take a
+``std::string``, which specifies when the certificate should start
+being valid, and when it should stop being valid. If you don't set the
+starting validity period, it will automatically choose the current
+time. If you don't set the ending time, it will choose the starting
+time plus a default time period. The arguments to these functions
+specify the time in the following format: "2002/11/27 1:50:14". The
+time is in 24-hour format, and the date is encoded as
+year/month/day. The date must be specified, but you can omit the time
+or trailing parts of it, for example "2002/11/27 1:50" or
+"2002/11/27".
+
+Lastly, you can set constraints on a key. The one you're mostly likely to want
+to use is to create (or request) a CA certificate, which can be done by calling
+the member function ``CA_key``. This should only be used when needed.
+
+Other constraints can be set by calling the member functions
+``add_constraints`` and ``add_ex_constraints``. The
+first takes a ``Key_Constraints`` value, and replaces any
+previously set value. If no value is set, then the certificate key is
+marked as being valid for any usage.  You can set it to any of the
+following (for more than one usage, OR them together):
+``DIGITAL_SIGNATURE``, ``NON_REPUDIATION``,
+``KEY_ENCIPHERMENT``, ``DATA_ENCIPHERMENT``,
+``KEY_AGREEMENT``, ``KEY_CERT_SIGN``, ``CRL_SIGN``,
+``ENCIPHER_ONLY``, ``DECIPHER_ONLY``. Many of these have quite
+special semantics, so you should either consult the appropriate
+standards document (such as RFC 3280), or just not call
+``add_constraints``, in which case the appropriate values will
+be chosen for you.
+
+The second function, ``add_ex_constraints``, allows you to specify an
+OID that has some meaning with regards to restricting the key to
+particular usages. You can, if you wish, specify any OID you like, but
+there is a set of standard ones that other applications will be able
+to understand. These are the ones specified by the PKIX standard, and
+are named "PKIX.ServerAuth" (for TLS server authentication),
+"PKIX.ClientAuth" (for TLS client authentication), "PKIX.CodeSigning",
+"PKIX.EmailProtection" (most likely for use with S/MIME),
+"PKIX.IPsecUser", "PKIX.IPsecTunnel", "PKIX.IPsecEndSystem", and
+"PKIX.TimeStamping". You can call "add_ex_constraints" any number of
+times~--~each new OID will be added to the list to include in the
+certificate.
diff --git a/doc/examples/GNUmakefile b/examples/GNUmakefile
index 44fcfeea5..44fcfeea5 100644
--- a/doc/examples/GNUmakefile
+++ b/examples/GNUmakefile
diff --git a/doc/examples/asn1.cpp b/examples/asn1.cpp
index b0a6aa104..b0a6aa104 100644
--- a/doc/examples/asn1.cpp
+++ b/examples/asn1.cpp
diff --git a/doc/examples/base64.cpp b/examples/base64.cpp
index dbe8d19e3..dbe8d19e3 100644
--- a/doc/examples/base64.cpp
+++ b/examples/base64.cpp
diff --git a/doc/examples/bcrypt.cpp b/examples/bcrypt.cpp
index 27a98cf33..27a98cf33 100644
--- a/doc/examples/bcrypt.cpp
+++ b/examples/bcrypt.cpp
diff --git a/doc/examples/bench.cpp b/examples/bench.cpp
index 20e6ec40b..20e6ec40b 100644
--- a/doc/examples/bench.cpp
+++ b/examples/bench.cpp
diff --git a/doc/examples/benchmark.cpp b/examples/benchmark.cpp
index 7ad1775e2..7ad1775e2 100644
--- a/doc/examples/benchmark.cpp
+++ b/examples/benchmark.cpp
diff --git a/doc/examples/bzip.cpp b/examples/bzip.cpp
index 6137bb6af..6137bb6af 100644
--- a/doc/examples/bzip.cpp
+++ b/examples/bzip.cpp
diff --git a/doc/examples/ca.cpp b/examples/ca.cpp
index 8dd3e981f..8dd3e981f 100644
--- a/doc/examples/ca.cpp
+++ b/examples/ca.cpp
diff --git a/doc/examples/cert_verify.cpp b/examples/cert_verify.cpp
index 04bcbecad..04bcbecad 100644
--- a/doc/examples/cert_verify.cpp
+++ b/examples/cert_verify.cpp
diff --git a/doc/examples/checksum.cpp b/examples/checksum.cpp
index dba7a7d70..dba7a7d70 100644
--- a/doc/examples/checksum.cpp
+++ b/examples/checksum.cpp
diff --git a/doc/examples/cms_dec.cpp b/examples/cms_dec.cpp
index 84355fb4a..84355fb4a 100644
--- a/doc/examples/cms_dec.cpp
+++ b/examples/cms_dec.cpp
diff --git a/doc/examples/cms_enc.cpp b/examples/cms_enc.cpp
index 2cf813987..2cf813987 100644
--- a/doc/examples/cms_enc.cpp
+++ b/examples/cms_enc.cpp
diff --git a/doc/examples/cpuid.cpp b/examples/cpuid.cpp
index 6d4cc7593..6d4cc7593 100644
--- a/doc/examples/cpuid.cpp
+++ b/examples/cpuid.cpp
diff --git a/doc/examples/cryptobox.cpp b/examples/cryptobox.cpp
index 38d750d17..38d750d17 100644
--- a/doc/examples/cryptobox.cpp
+++ b/examples/cryptobox.cpp
diff --git a/doc/examples/decrypt.cpp b/examples/decrypt.cpp
index ea510c5e9..ea510c5e9 100644
--- a/doc/examples/decrypt.cpp
+++ b/examples/decrypt.cpp
diff --git a/doc/examples/dh.cpp b/examples/dh.cpp
index 652c7b136..652c7b136 100644
--- a/doc/examples/dh.cpp
+++ b/examples/dh.cpp
diff --git a/doc/examples/dsa_kgen.cpp b/examples/dsa_kgen.cpp
index fe3157370..fe3157370 100644
--- a/doc/examples/dsa_kgen.cpp
+++ b/examples/dsa_kgen.cpp
diff --git a/doc/examples/dsa_sign.cpp b/examples/dsa_sign.cpp
index 5f02c0dc1..5f02c0dc1 100644
--- a/doc/examples/dsa_sign.cpp
+++ b/examples/dsa_sign.cpp
diff --git a/doc/examples/dsa_ver.cpp b/examples/dsa_ver.cpp
index a666259c1..a666259c1 100644
--- a/doc/examples/dsa_ver.cpp
+++ b/examples/dsa_ver.cpp
diff --git a/doc/examples/eax_test.cpp b/examples/eax_test.cpp
index 32311800d..32311800d 100644
--- a/doc/examples/eax_test.cpp
+++ b/examples/eax_test.cpp
diff --git a/doc/examples/eax_tv.txt b/examples/eax_tv.txt
index 95cd7c1ab..95cd7c1ab 100644
--- a/doc/examples/eax_tv.txt
+++ b/examples/eax_tv.txt
diff --git a/doc/examples/ecdsa.cpp b/examples/ecdsa.cpp
index df1e1b93a..df1e1b93a 100644
--- a/doc/examples/ecdsa.cpp
+++ b/examples/ecdsa.cpp
diff --git a/doc/examples/encrypt.cpp b/examples/encrypt.cpp
index 28017d875..28017d875 100644
--- a/doc/examples/encrypt.cpp
+++ b/examples/encrypt.cpp
diff --git a/doc/examples/encrypt2.cpp b/examples/encrypt2.cpp
index 41f4fb478..41f4fb478 100644
--- a/doc/examples/encrypt2.cpp
+++ b/examples/encrypt2.cpp
diff --git a/doc/examples/factor.cpp b/examples/factor.cpp
index 58b12d9a5..58b12d9a5 100644
--- a/doc/examples/factor.cpp
+++ b/examples/factor.cpp
diff --git a/doc/examples/fpe.cpp b/examples/fpe.cpp
index 9b18d4879..9b18d4879 100644
--- a/doc/examples/fpe.cpp
+++ b/examples/fpe.cpp
diff --git a/doc/examples/gen_certs.cpp b/examples/gen_certs.cpp
index f8c9fe124..f8c9fe124 100644
--- a/doc/examples/gen_certs.cpp
+++ b/examples/gen_certs.cpp
diff --git a/doc/examples/gtk/Makefile b/examples/gtk/Makefile
index 10e069bb3..10e069bb3 100644
--- a/doc/examples/gtk/Makefile
+++ b/examples/gtk/Makefile
diff --git a/doc/examples/gtk/dsa.cpp b/examples/gtk/dsa.cpp
index 2cd91b0e8..2cd91b0e8 100644
--- a/doc/examples/gtk/dsa.cpp
+++ b/examples/gtk/dsa.cpp
diff --git a/doc/examples/gtk/gtk_ui.cpp b/examples/gtk/gtk_ui.cpp
index d4e9cd238..d4e9cd238 100644
--- a/doc/examples/gtk/gtk_ui.cpp
+++ b/examples/gtk/gtk_ui.cpp
diff --git a/doc/examples/gtk/gtk_ui.h b/examples/gtk/gtk_ui.h
index 065a4f76b..065a4f76b 100644
--- a/doc/examples/gtk/gtk_ui.h
+++ b/examples/gtk/gtk_ui.h
diff --git a/doc/examples/gtk/readme.txt b/examples/gtk/readme.txt
index 4f3691166..4f3691166 100644
--- a/doc/examples/gtk/readme.txt
+++ b/examples/gtk/readme.txt
diff --git a/doc/examples/hash.cpp b/examples/hash.cpp
index 1a4ca1b64..1a4ca1b64 100644
--- a/doc/examples/hash.cpp
+++ b/examples/hash.cpp
diff --git a/doc/examples/hash_fd.cpp b/examples/hash_fd.cpp
index 32acdbec3..32acdbec3 100644
--- a/doc/examples/hash_fd.cpp
+++ b/examples/hash_fd.cpp
diff --git a/doc/examples/hash_quickly.cpp b/examples/hash_quickly.cpp
index 005a6d719..005a6d719 100644
--- a/doc/examples/hash_quickly.cpp
+++ b/examples/hash_quickly.cpp
diff --git a/doc/examples/hasher.cpp b/examples/hasher.cpp
index e5c52ba55..e5c52ba55 100644
--- a/doc/examples/hasher.cpp
+++ b/examples/hasher.cpp
diff --git a/doc/examples/hasher2.cpp b/examples/hasher2.cpp
index b6303b644..b6303b644 100644
--- a/doc/examples/hasher2.cpp
+++ b/examples/hasher2.cpp
diff --git a/doc/examples/keywrap.cpp b/examples/keywrap.cpp
index 730bcb6c9..730bcb6c9 100644
--- a/doc/examples/keywrap.cpp
+++ b/examples/keywrap.cpp
diff --git a/doc/examples/make_prime.cpp b/examples/make_prime.cpp
index acaaac698..acaaac698 100644
--- a/doc/examples/make_prime.cpp
+++ b/examples/make_prime.cpp
diff --git a/doc/examples/new_engine.cpp b/examples/new_engine.cpp
index 42e5dbe33..42e5dbe33 100644
--- a/doc/examples/new_engine.cpp
+++ b/examples/new_engine.cpp
diff --git a/doc/examples/package.cpp b/examples/package.cpp
index 02cf52816..02cf52816 100644
--- a/doc/examples/package.cpp
+++ b/examples/package.cpp
diff --git a/doc/examples/passhash.cpp b/examples/passhash.cpp
index 586c28c3f..586c28c3f 100644
--- a/doc/examples/passhash.cpp
+++ b/examples/passhash.cpp
diff --git a/doc/examples/pkcs10.cpp b/examples/pkcs10.cpp
index 3f5ec8e05..3f5ec8e05 100644
--- a/doc/examples/pkcs10.cpp
+++ b/examples/pkcs10.cpp
diff --git a/doc/examples/pqg_gen.cpp b/examples/pqg_gen.cpp
index c033dac3b..c033dac3b 100644
--- a/doc/examples/pqg_gen.cpp
+++ b/examples/pqg_gen.cpp
diff --git a/doc/python/cipher.py b/examples/python/cipher.py
index 1be2759ae..1be2759ae 100755
--- a/doc/python/cipher.py
+++ b/examples/python/cipher.py
diff --git a/doc/python/cryptobox.py b/examples/python/cryptobox.py
index f76ed6bc3..f76ed6bc3 100755
--- a/doc/python/cryptobox.py
+++ b/examples/python/cryptobox.py
diff --git a/doc/python/nisttest.py b/examples/python/nisttest.py
index 3ea8fda0f..3ea8fda0f 100755
--- a/doc/python/nisttest.py
+++ b/examples/python/nisttest.py
diff --git a/doc/python/results.txt b/examples/python/results.txt
index 7a3824001..7a3824001 100644
--- a/doc/python/results.txt
+++ b/examples/python/results.txt
diff --git a/doc/python/rng_test.py b/examples/python/rng_test.py
index 06c79b84e..06c79b84e 100755
--- a/doc/python/rng_test.py
+++ b/examples/python/rng_test.py
diff --git a/doc/python/rsa.py b/examples/python/rsa.py
index 8ca95ff8b..8ca95ff8b 100755
--- a/doc/python/rsa.py
+++ b/examples/python/rsa.py
diff --git a/doc/examples/read_ssh.cpp b/examples/read_ssh.cpp
index f6299a29d..f6299a29d 100644
--- a/doc/examples/read_ssh.cpp
+++ b/examples/read_ssh.cpp
diff --git a/doc/examples/readme.txt b/examples/readme.txt
index fb6a03ddf..fb6a03ddf 100644
--- a/doc/examples/readme.txt
+++ b/examples/readme.txt
diff --git a/doc/examples/rng_test.cpp b/examples/rng_test.cpp
index c0d24fd80..c0d24fd80 100644
--- a/doc/examples/rng_test.cpp
+++ b/examples/rng_test.cpp
diff --git a/doc/examples/row_encryptor.cpp b/examples/row_encryptor.cpp
index 685850945..685850945 100644
--- a/doc/examples/row_encryptor.cpp
+++ b/examples/row_encryptor.cpp
diff --git a/doc/examples/rsa_dec.cpp b/examples/rsa_dec.cpp
index 81592328c..81592328c 100644
--- a/doc/examples/rsa_dec.cpp
+++ b/examples/rsa_dec.cpp
diff --git a/doc/examples/rsa_enc.cpp b/examples/rsa_enc.cpp
index ac609c4b3..ac609c4b3 100644
--- a/doc/examples/rsa_enc.cpp
+++ b/examples/rsa_enc.cpp
diff --git a/doc/examples/rsa_kgen.cpp b/examples/rsa_kgen.cpp
index f4566263b..f4566263b 100644
--- a/doc/examples/rsa_kgen.cpp
+++ b/examples/rsa_kgen.cpp
diff --git a/doc/examples/rsa_manykey.cpp b/examples/rsa_manykey.cpp
index e6a511753..e6a511753 100644
--- a/doc/examples/rsa_manykey.cpp
+++ b/examples/rsa_manykey.cpp
diff --git a/doc/examples/self_sig.cpp b/examples/self_sig.cpp
index 6710cfb51..6710cfb51 100644
--- a/doc/examples/self_sig.cpp
+++ b/examples/self_sig.cpp
diff --git a/doc/examples/sig_gen.cpp b/examples/sig_gen.cpp
index cf273216a..cf273216a 100644
--- a/doc/examples/sig_gen.cpp
+++ b/examples/sig_gen.cpp
diff --git a/doc/examples/stack.cpp b/examples/stack.cpp
index 0c00ed183..0c00ed183 100644
--- a/doc/examples/stack.cpp
+++ b/examples/stack.cpp
diff --git a/doc/examples/tls_client.cpp b/examples/tls_client.cpp
index 10ead20cc..10ead20cc 100644
--- a/doc/examples/tls_client.cpp
+++ b/examples/tls_client.cpp
diff --git a/doc/examples/tls_server.cpp b/examples/tls_server.cpp
index da13953f8..da13953f8 100644
--- a/doc/examples/tls_server.cpp
+++ b/examples/tls_server.cpp
diff --git a/doc/examples/toolbox.cpp b/examples/toolbox.cpp
index 622a1f56f..622a1f56f 100644
--- a/doc/examples/toolbox.cpp
+++ b/examples/toolbox.cpp
diff --git a/doc/examples/tss.cpp b/examples/tss.cpp
index 03d7699bf..03d7699bf 100644
--- a/doc/examples/tss.cpp
+++ b/examples/tss.cpp
diff --git a/doc/examples/x509info.cpp b/examples/x509info.cpp
index b22b4ebd8..b22b4ebd8 100644
--- a/doc/examples/x509info.cpp
+++ b/examples/x509info.cpp
diff --git a/readme.txt b/readme.txt
index a65159ee8..ea26a37b7 100644
--- a/readme.txt
+++ b/readme.txt
@@ -2,29 +2,14 @@ Botan 1.9.16-dev, ????-??-??
 http://botan.randombit.net/
 
 Botan is a C++ class library for performing a wide variety of
-cryptographic operations.
+cryptographic operations. It is released under the 2 clause BSD
+license; see doc/license.txt for the specifics. You can file bugs in
+Bugzilla (http://bugs.randombit.net/) or by sending a report to the
+botan-devel mailing list. More information about the mailing list is
+at http://lists.randombit.net/mailman/listinfo/botan-devel/
 
-Botan is released under the FreeBSD license (see doc/license.txt for
-the specifics). More information about the authors and contributors
-can be found in doc/credits.txt and doc/thanks.txt.
+You can find documentation online at http://botan.randombit.net/manual
+and http://botan.randombit.net/doxygen. A set of example programs can
+be found in the examples directory.
 
-You can file bugs at http://bugs.randombit.net/ or by sending a report
-to the botan-devel mailing list:
-  http://lists.randombit.net/mailman/listinfo/botan-devel/
-
-In the doc directory, there should be a set of PDFs, including
-  building.pdf - build instructions
-  api.pdf - the API reference manual
-  tutorial.pdf - a set of simple examples and tutorials
-
-A set of example programs can be found in the doc/examples directory.
-You can also find Doxygen generated documentation online at
-  http://botan.randombit.net/doxygen
-
-Check the project website for announcements and new releases. If
-you'll be developing code using this library, consider joining the
-mailing lists to keep up to date with changes.
-
-As always, feel free to contact me with any questions or comments.
-
- - Jack Lloyd ([email protected])
+Jack Lloyd ([email protected])
diff --git a/src/block/aes/aes.cpp b/src/block/aes/aes.cpp
index 9fb12cd11..5f47762a8 100644
--- a/src/block/aes/aes.cpp
+++ b/src/block/aes/aes.cpp
@@ -2,6 +2,8 @@
 * AES
 * (C) 1999-2010 Jack Lloyd
 *
+* Based on the public domain reference implemenation
+*
 * Distributed under the terms of the Botan license
 */
 
diff --git a/src/block/des/des.cpp b/src/block/des/des.cpp
index 739dfe87c..c500e9bab 100644
--- a/src/block/des/des.cpp
+++ b/src/block/des/des.cpp
@@ -2,6 +2,9 @@
 * DES
 * (C) 1999-2008 Jack Lloyd
 *
+* Based on a public domain implemenation by Phil Karn (who in turn
+* credited Richard Outerbridge and Jim Gillogly)
+*
 * Distributed under the terms of the Botan license
 */
 
diff --git a/src/block/serpent/serpent.cpp b/src/block/serpent/serpent.cpp
index 1d940cf39..b3cf0f6c9 100644
--- a/src/block/serpent/serpent.cpp
+++ b/src/block/serpent/serpent.cpp
@@ -2,6 +2,9 @@
 * Serpent
 * (C) 1999-2007 Jack Lloyd
 *
+* The sbox expressions used here were discovered by Dag Arne Osvik and
+* are described in his paper "Speeding Up Serpent".
+*
 * Distributed under the terms of the Botan license
 */
 
diff --git a/src/block/square/square.cpp b/src/block/square/square.cpp
index b1517b990..cd1865582 100644
--- a/src/block/square/square.cpp
+++ b/src/block/square/square.cpp
@@ -2,6 +2,8 @@
 * Square
 * (C) 1999-2007 Jack Lloyd
 *
+* Based on the public domain reference implemenation
+*
 * Distributed under the terms of the Botan license
 */
 
diff --git a/src/block/twofish/twofish.cpp b/src/block/twofish/twofish.cpp
index 41bc7ca1c..c0735e202 100644
--- a/src/block/twofish/twofish.cpp
+++ b/src/block/twofish/twofish.cpp
@@ -2,6 +2,9 @@
 * Twofish
 * (C) 1999-2007 Jack Lloyd
 *
+* The key schedule implemenation is based on a public domain
+* implementation by Matthew Skala
+*
 * Distributed under the terms of the Botan license
 */