merge of '4d21273f3094d6b2c2bc149c76383d54ce0a0006'

     and 'b4c266ae827b5a19f0cc07dc9b55a95fd4915a1e'

2 files changed, 62 insertions, 56 deletions

diff --git a/doc/api.tex b/doc/api.tex
index c1469418a..d8d1d4d57 100644
--- a/doc/api.tex
+++ b/doc/api.tex
@@ -12,7 +12,7 @@
 
 \title{\textbf{Botan API Reference}}
 \author{}
-\date{2008/11/17}
+\date{2009/2/10}
 
 \newcommand{\filename}[1]{\texttt{#1}}
 \newcommand{\manpage}[2]{\texttt{#1}(#2)}
@@ -62,7 +62,7 @@ obvious choice. However in most cases this is not an issue, as many
 algorithms are specified in terms of 32-bit operations precisely to
 target commodity processors.
 
-Smaller andhelds, set-top boxes, and the bigger smart phones and smart
+Smaller handhelds, set-top boxes, and the bigger smart phones and smart
 cards, are also capable of using Botan. However, Botan uses a fairly
 large amount of code space (up to several megabytes, depending upon
 the compiler and options used), which could be prohibitive in some
@@ -77,7 +77,7 @@ to give them such an object for that algorithm.
 \subsection{Why Botan?}
 
 Botan may be the perfect choice for your application. Or it might be a
-terribly bad idea. This section is basically to make it clear what Botan is
+terribly bad idea. This section will make clear what Botan is
 and is not.
 
 First, let's cover the major strengths:
@@ -94,7 +94,7 @@ First, let's cover the major strengths:
         public key algorithms and standards (such as IEEE 1363, PKCS, and
         X.509v3).
 
-  \item Supports a name-based lookup scheme, so you can get ahold of any
+  \item Supports a name-based lookup scheme, so you can get a hold of any
         algorithm on the fly.
 
   \item You can easily extend much of the system at application compile time or
@@ -141,7 +141,7 @@ And the major downsides and deficiencies are:
 With a very small number of exceptions, declarations in the library
 are contained within the namespace \namespace{Botan}. Botan declares
 several typedef'ed types to help buffer it against changes in machine
-architecture.  These types are used extensively in the interface, and
+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
@@ -158,10 +158,10 @@ should be used with the \filename{botan/} prefix in your actual code.
 
 There are a set of core services which the library needs access to
 while it is performing requests. To ensure these are set up, you must
-create a \type{LibraryInitializer} object (using called 'init' in
+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
-objects lifetime must exceed that of all other Botan objects your
+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
@@ -195,7 +195,7 @@ 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 (and thus for the internal library state as well).
+for the operations (thus for the internal library state as well).
 
 \subsection{Gotchas}
 
@@ -721,7 +721,7 @@ And remember: if you're resetting both values, reset the key \emph{first}.
 
 \subsubsection{Cipher Filters}
 
-Getting ahold of a \type{Filter} implementing a cipher is very easy. Simply
+Getting a hold of a \type{Filter} implementing a cipher is very easy. Simply
 make sure you're including the header \filename{lookup.h}, and call
 \function{get\_cipher}. Generally you will pass the return value directly into
 a \type{Pipe}. There are actually a couple different functions, which do pretty
@@ -1161,7 +1161,7 @@ methods are particularly useful for these algorithms.
 
 \subsection{Key Agreement}
 
-You can get ahold of a \type{PK\_Key\_Agreement\_Scheme} object by calling
+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'',
@@ -1581,7 +1581,7 @@ functions:
 
 \function{add\_trusted\_certs}(\type{DataSource\&} \arg{source})
 
-The versions that take a \type{DataSource\&} will add all of the certificates
+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
@@ -1938,7 +1938,7 @@ 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, later in
+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,
@@ -2169,13 +2169,13 @@ To ensure good quality output, a PRNG needs to be seeded with truly random data
 \type{u32bit} \arg{length}) or (better), use the \type{EntropySource}
 interface.
 
-One a PRNG has been initialized, you can get a single byte of random data by
+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 problem inherent to seeding the PRNG by using the
+You can avoid all the problems inherent in seeding the PRNG by using the
 globally shared PRNG, described later in this section.
 
 \subsection{Randpool}
@@ -2186,7 +2186,7 @@ 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
-remainer of this section is a (fairly technical, though high-level) description
+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.
 
@@ -2198,7 +2198,7 @@ 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 of the sizes internally would double. Every time
+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
@@ -2228,7 +2228,7 @@ 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 recieves entropy, it simply passes it along to the PRNG it
+PRNG object receives entropy, it simply 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.
@@ -2254,7 +2254,7 @@ 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} which asked for the entropy, and thus any hashing
+\type{RandomNumberGenerator} which asked for the entropy, thus any hashing
 you do will be wasteful of both CPU cycles and possibly entropy.
 
 \pagebreak
@@ -2314,7 +2314,7 @@ There is an example \type{UI} which 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, wxWindows, FOX, etc), and would like to make it available to users
+(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.
 
@@ -3002,7 +3002,7 @@ match that in SCAN, if it's defined there).
 
 \subsection{Compatibility}
 
-Generally, cryptographic algorithms are well standardized, and thus
+Generally, cryptographic algorithms are well standardized, thus
 compatibility between implementations is relatively simple (of course, not all
 algorithms are supported by all implementations). But there are a few
 algorithms which are poorly specified, and these should be avoided if you wish
diff --git a/doc/tutorial.tex b/doc/tutorial.tex
index 9dcd80ff8..dc171d197 100644
--- a/doc/tutorial.tex
+++ b/doc/tutorial.tex
@@ -10,10 +10,10 @@
 \setlength{\oddsidemargin}{0in}
 \setlength{\evensidemargin}{0in}
 
-\title{\textbf{Botan 1.4.x Tutorial}}
+\title{\textbf{Botan Tutorial}}
 \author{Jack Lloyd \\
         \texttt{[email protected]}}
-\date{}
+\date{2009/2/10}
 
 \newcommand{\filename}[1]{\texttt{#1}}
 \newcommand{\manpage}[2]{\texttt{#1}(#2)}
@@ -36,11 +36,12 @@
 
 \section{Introduction}
 
-This document essentially sets up various simple scenarios and then shows how
-to solve the problems using Botan 1.4.x. It's fairly simple, and doesn't cover
-many of the available APIs and algorithms, especially the more obscure or
-unusual ones. It is a supplement to the API documentation and the example
-applications, which are included in the distribution.
+This document essentially sets up various simple scenarios and then
+shows how to solve the problems using Botan. It's fairly simple, and
+doesn't cover many of the available APIs and algorithms, especially
+the more obscure or unusual ones. It is a supplement to the API
+documentation and the example applications, which are included in the
+distribution.
 
 To quote the Perl man page: '``There's more than one way to do it.'' Divining
 how many more is left as an exercise to the reader.'
@@ -53,7 +54,7 @@ just written down from memory. If you find errors, please let me know.
 
 \section{Initializing the Library}
 
-The first step to using Botan is the create a \type{LibraryInitializer} object,
+The first step to using Botan is to create a \type{LibraryInitializer} object,
 which handles creating various internal structures, and also destroying them at
 shutdown. Essentially:
 
@@ -79,7 +80,7 @@ int main()
 
 Probably the most common crypto problem is encrypting a file (or some data that
 is in-memory) using a passphrase. There are a million ways to do this, most of
-them bad. In particular, you've have to protect against weak passphrases,
+them bad. In particular, you have to protect against weak passphrases,
 people reusing a passphrase many times, accidental and deliberate modification,
 and a dozen other potential problems.
 
@@ -95,12 +96,12 @@ generating the keys. For production code, another algorithm (such as TripleDES
 or AES) may be more appropriate. Whenever we need a hash function, we'll use
 SHA-1, since that is a common and well-known hash that is thought to be secure.
 
-In all examples, we choose to derive the IV from the passphrase. Another
-(probably more common) alternative is to generate the IV randomly and include
-it at the beginning of the message. Either way is acceptable, and can be
-secure. The method used here was chosen to make for more interesting examples
-(because it's harder to get right), and may not be an appropriate choice for
-some environments.
+In all examples, we choose to derive the Initialization Vector (IV) from the
+passphrase. Another (probably more common) alternative is to generate the IV
+randomly and include it at the beginning of the message. Either way is
+acceptable, and can be secure. The method used here was chosen to make for more
+interesting examples (because it's harder to get right), and may not be an
+appropriate choice for some environments.
 
 First, some notation. The passphrase is stored as a \type{std::string} named
 \variable{passphrase}. The input and output files (\variable{infile} and
@@ -131,7 +132,7 @@ it, and truncate it to 8 bytes (which is Blowfish's block size).
 \subsubsection{Problem 1: Buffering}
 
 There is a problem with the above code, if the input file is fairly large as
-compared to available memory. Specifically, all of the encrypted data is stored
+compared to available memory. Specifically, all the encrypted data is stored
 in memory, and then flushed to \variable{outfile} in a single go at the very
 end. If the input file is big (say, a gigabyte), this will be most problematic.
 
@@ -157,16 +158,19 @@ do is introduce a salt (or nonce) into the generation of the key from the
 passphrase. This will mean that the key will not be the same each time the same
 passphrase is typed in by a user.
 
-There is another problem with using a bare hash function to derive keys. While
-it's inconceivable that an attacker could brute-force a 160-bit key, it would
-be fairly simple for them to compute the SHA-1 hashes of various common
-passwords ('password', the name of the dog, SO's middle name, etc) and try
-those as keys. So we want to slow the attacker down if we can, and an easy way
-to do that is to iterate the hash function a bunch of times (say, 1024 to 4096
-times). This will involve only a small amount of effort for a legitimate user
-(since they only have to compute the hashes once, when they type in their
-passphrase), but an attacker, trying out a large list of potential passphrases,
-will be seriously annoyed by this.
+There is another problem with using a bare hash function to derive
+keys. While it's inconceivable (based on our current understanding of
+thermodynamics and theories of computation) that an attacker could
+brute-force a 160 bit key, it would be fairly simple for them to
+compute the SHA-1 hashes of various common passwords ('password', the
+name of the dog, the significant other's middle name, favorite sports
+team) and try those as keys. So we want to slow the attacker down if
+we can, and an easy way to do that is to iterate the hash function a
+bunch of times (say, 1024 to 4096 times). This will involve only a
+small amount of effort for a legitimate user (since they only have to
+compute the hashes once, when they type in their passphrase), but an
+attacker, trying out a large list of potential passphrases, will be
+seriously annoyed by this.
 
 In this iteration of the example, we'll kill these two birds with one stone,
 and derive the key from the passphrase using a S2K (string to key) algorithm
@@ -275,7 +279,7 @@ different values.
 
 \subsubsection{Final version}
 
-Here is the final version of the encryption code, with all of the changes we've
+Here is the final version of the encryption code, with all the changes we've
 made:
 
 \begin{verbatim}
@@ -413,7 +417,7 @@ response seems warranted, so we'll use SHA-1.
 
 Upon receiving the response from the client, the server computes what the
 response should have been based on the challenge it sent out, and the
-passphrase. If the two responses match, the the client is authenticated.
+passphrase. If the two responses match, the client is authenticated.
 Otherwise, it is not.
 
 An alternate method is to use PBKDF2 again, using the challenge as the salt. In
@@ -514,11 +518,13 @@ EMSA1 with SHA-1.
   byte msg[] = { /* ... */ };
 
   /*
-     You can also repeatedly call update(const byte[], u32bit), followed by a
-     call to signature(), which will return the final sig of all the date that
-     was passed through update(). sign_message() is just a stub that calls
-     update() once, and returns the value of signature().
+  You can also repeatedly call update(const byte[], u32bit), followed
+  by a call to signature(), which will return the final signature of
+  all the data that was passed through update(). sign_message() is
+  just a stub that calls update() once, and returns the value of
+  signature().
   */
+
   SecureVector<byte> signature = signer->sign_message(msg, sizeof(msg));
 \end{verbatim}
 
@@ -526,7 +532,7 @@ EMSA1 with SHA-1.
 
 \subsubsection{Signature Verification}
 
-In addition to all of the problems with choosing the correct padding method,
+In addition to all the problems with choosing the correct padding method,
 there is yet another complication with verifying a signature. Namely, there are
 two varieties of signature algorithms - those providing message recovery (that
 is, the value that was signed can be directly recovered by someone verifying
@@ -749,11 +755,11 @@ certificate in PEM encoding.
 Verifying a certificate requires that we build up a chain of trust, starting
 from the root (usually a commercial CA), down through some number of
 intermediate CAs, and finally reaching the actual certificate in
-question. Thus, to verify, we actually have to have all of those certificates
+question. Thus, to verify, we actually have to have all those certificates
 on hand (or at the very least, know where we can get the ones we need).
 
 The class which handles both storing certificates, and verifying them, is
-called \type{X509\_Store}. We'll start by assuming that we have all of the
+called \type{X509\_Store}. We'll start by assuming that we have all the
 certificates we need, and just want to verify a cert. This is done by calling
 the member function \function{validate\_cert}, which takes the
 \type{X509\_Certificate} in question, and an optional argument of type
@@ -786,7 +792,7 @@ WRITEME
 
 \section{Special Topics}
 
-This chapter is for subject which don't really fit into the API documentation
+This chapter is for subjects which don't really fit into the API documentation
 or into other chapters of the tutorial.
 
 \subsection{GUIs}