diff options
| -rw-r--r-- | doc/api.tex | 40 | ||||
| -rw-r--r-- | doc/tutorial.tex | 78 |
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} |