diff options
| -rw-r--r-- | doc/api.tex | 808 |
1 files changed, 393 insertions, 415 deletions
diff --git a/doc/api.tex b/doc/api.tex index 8ba06d158..8f2d88a59 100644 --- a/doc/api.tex +++ b/doc/api.tex @@ -976,8 +976,21 @@ for your filters, depending on what you have in mind. \pagebreak \section{Public Key Cryptography} -Public key algorithms were added in Botan 0.8.0. The major base classes can be -found in \filename{pubkey.h}. +Let's create an RSA private key: + +\begin{verbatim} + RSA_PrivateKey priv_rsa(1024 /* bits */); +\end{verbatim} + +We can easily turn this into a public key, which we can then send to +someone: + +\begin{verbatim} + RSA_PublicKey pub_rsa = priv_rsa; +\end{verbatim} + + + \subsection{Creating PK Algorithm Key Objects} @@ -2164,39 +2177,6 @@ A MAC has the \type{SymmetricAlgorithm} interface in addition to the \type{BufferedComputation} interface. \pagebreak -\section{CMS} - -The Cryptographic Message Syntax (CMS) is an IETF standardized format for -message encryption and signatures. It is based on PKCS \#7, but has been -extended to allow compression, authentication, and password based encryption. -Some simple uses of CMS will inter-operate with PKCS \#7 implementations, but -most uses will cause incompatibilities. - -CMS is based on the idea of layering. At the lowest level is a data type (the -actual message), which is encapsulated in another layer, for example one that -provides encryption or adds a signature. This layer can in turn be encapsulated -in another layer, and so on as often as you like. - -\emph{Note that CMS is not available in the current distribution. You can -download an alpha version separately from the website.} - -\subsection{Encoding} - -The CMS encoder included in Botan does not allow you to use the full range of -options available; for example, when signing, you can only sign with one key at -a time (this particular restriction may be changed in later versions). However, -you can do repeated signature operations, signing the previously signed -data. Semantically, this is not quite the same (since the second and later -signatures sign the signatures that came before it, as well as the data), but -practically speaking it's the same thing. - -WRITEME - -\subsection{Decoding} - -WRITEME - -\pagebreak \section{Random Number Generators} The random number generators provided in Botan are meant for creating keys, @@ -2866,6 +2846,288 @@ some_thing = 1.2.3 # some OID another_thing = some_thing.4.5 # another_thing = 1.2.3.4.5 \end{verbatim} + +\pagebreak +\section{Botan's Modules} + +Botan comes with a variety of modules which 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 fairly 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 fairly 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 simply 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} which 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} which will specify what +type of CAPI provider to use. Generally the CAPI RNG is always the same +software-based PRNG, but there are a few which may use a hardware RNG. By +default it will use the first provider listed in the option +``rng/ms\_capi\_prov\_type'' which 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 which 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 pretty 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 fairly 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. It's 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} which takes +arbitrary amounts of input, and produces no output. Generally, 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 which 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 actually be used. + +\subsection{Writing Modules} + +It's a lot simpler to write modules for Botan that it is to write code +in the core library, for several reasons. First, a module can rely on +external libraries and services beyond the base ISO C++ libraries, and +also machine dependent features. Also, the code can be added at +configuration time on the user's end with very little effort (\ie the +code can be distributed separately, and included by the user without +needing to patch any existing source files). + +Each module lives in a subdirectory of the \filename{modules} +directory, which exists at the top-level of the Botan source tree. The +``short name'' of the module is the same as the name of this +directory. The only required file in this directory is +\filename{modinfo.txt}, which contains directives that specify what a +particular module does, what systems it runs on, and so on. Comments +in \filename{modinfo.txt} start with a \verb|#| character and continue +to end of line. + +Recognized directives include: + +\newcommand{\directive}[2]{ + \vskip 4pt + \noindent + \texttt{#1}: #2 +} + +\directive{realname <name>}{Specify that the 'real world' name of this module + is \texttt{<name>}.} + +\directive{note <note>}{Add a note that will be seen by the end-user at +configure time if the module is included into the library.} + +\directive{require\_version <version>}{Require at configure time that +the version of Botan in use be at least \texttt{<version>}.} + +\directive{define <macro>[,<macro>[,...]]}{Cause the macro + \macro{BOTAN\_EXT\_<macro>} (for each instance of \macro{<macro>} + in the directive) to be defined in \filename{build.h}. This should + only be used if the module creates user-visible changes. There is a + set of conventions that should be followed in deciding what to call + this macro (where xxx denotes some descriptive and distinguishing + characteristic of the thing implemented, such as + \macro{ALLOC\_MLOCK} or \macro{MUTEX\_PTHREAD}): + +\begin{itemize} +\item Allocator: \macro{ALLOC\_xxx} +\item Compressors: \macro{COMPRESSOR\_xxx} +\item EntropySource: \macro{ENTROPY\_SRC\_xxx} +\item Engines: \macro{ENGINE\_xxx} +\item Mutex: \macro{MUTEX\_xxx} +\item Timer: \macro{TIMER\_xxx} +\end{itemize} +} + +\directive{<libs> / </libs>}{This specifies any extra libraries to be +linked in. It is a mapping from OS to library name, for example +\texttt{linux -> rt}, which means that on Linux librt should be linked +in. You can also use ``all'' to force the library to be linked in on +all systems.} + +\directive{<add> / </add>}{Tell the configuration script to add the + files named between these two tags into the source tree. All these + files must exist in the current module directory.} + +\directive{<ignore> / </ignore>}{Tell the configuration script to + ignore the files named in the main source tree. This is useful, for + example, when replacing a C++ implementation with a pure assembly + version.} + +\directive{<replace> / </replace>}{Tell the configuration script to + ignore the file given in the main source tree, and instead use the + one in the module's directory.} + +Additionally, the module file can contain blocks, delimited by the +following pairs: + +\texttt{<os> / </os>}, \texttt{<arch> / </arch>}, \texttt{<cc> / </cc>} + +\noindent +For example, putting ``alpha'' and ``ia64'' in a \texttt{<arch>} block will +make the configuration script only allow the module to be compiled on those +architectures. Not having a block means any value is acceptable. + \pagebreak \section{Miscellaneous} @@ -3094,205 +3356,7 @@ example, if the \texttt{timer\_unix} module is available, one could call return of the \function{gettimeofday} function call. This is done automatically by the \type{LibraryInitializer} object. -\pagebreak -\section{Botan's Modules} - -Botan comes with a variety of modules which 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 fairly 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 fairly 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 simply 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} which 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} which will specify what -type of CAPI provider to use. Generally the CAPI RNG is always the same -software-based PRNG, but there are a few which may use a hardware RNG. By -default it will use the first provider listed in the option -``rng/ms\_capi\_prov\_type'' which 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 which 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 pretty 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 fairly 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. It's 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} which takes -arbitrary amounts of input, and produces no output. Generally, 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 which 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 actually be used. - -\pagebreak -\section{BigInt} +\subsection{BigInt} \type{BigInt} is Botan's implementation of a multiple-precision integer. Thanks to C++'s operator overloading features, using \type{BigInt} is @@ -3361,7 +3425,7 @@ GCD algorithm. primality test with fixed bases. For higher assurance, use \function{verify\_prime}, which uses more rounds and randomized 48-bit bases. -\subsection{Efficiency Hints} +\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 @@ -3382,159 +3446,42 @@ library knows what the assumptions are. The interfaces for these functions can change completely without notice. \pagebreak -\section{Removing Algorithms} - -You may well want to remove some of Botan's algorithms in order to fit it into -a memory-constrained system, where you're counting the kilobytes. For the most -part, this is trivial to do, and Botan's interface makes it easy for -applications to test for the presence of an algorithm at runtime, so a -well-behaved application can work without any need for porting on such an -version of Botan. - -In some versions of 1.3.x, you can use the 'minimal' module, which removes -large amount of Botan, including most ciphers and hashes (except AES, DES/3DES, -SHA-1, HMAC, RSA, DSA, and Diffie-Hellman), DLIES, EAX and CTS modes, and a few -other odds and ends. You can check for this being the case by seeing if -\macro{BOTAN\_EXT\_MINIMAL} is defined, though for the most part it's better to -use the lookup interface (since you have no way of knowing what exactly the -minimal module might remove from release to release, and certainly not if the -shared object you're linking to has a particular algorithm). This module was -removed just before 1.4.0, as there is a better way to handle all of this in -the new engine code, which is aware of things outside public key algorithms. +\section{Algorithms} -Removing things like the PK signature encoding schemes (EMSA2, EMSA3...) is -somewhat more complicated and not documented here (thought it is actually quite -simple if you know how to do it -- the minimal module shows how). This tutorial -(of sorts) will go through the steps required to compile a version of Botan -without the Blowfish block cipher (which has been included since the first -release of Botan, in the spring of 2001). +\subsection{Recommended Algorithms} -The first step is to remove the files \filename{include/blowfish.h}, -\filename{src/blowfish.cpp}, and \filename{src/blfs\_tab.cpp}, which actually -implement the algorithm. Then minor editing of \filename{src/algolist.cpp} is -required. First, remove the line that includes the Blowfish header -\filename{botan/blowfish.h}. Then look in \function{get\_block\_cipher} for the -code that adds a Blowfish block cipher object to the internal lookup table, and -remove it. Run the configure script, and then \textbf{make} the library. Tada! -Done. - -So how does an application test for such a situation? The first is to simply -try to pass the name ``Blowfish'' to constructor of \type{CBC\_Encryption} or -other Botan \type{Filter}, and catch the resulting exception. This is not -particularly flexible, though. If an application wants to check on the status -of Botan's support for a particular algorithm, it can call some status -functions found in \filename{lookup.h}, called \function{have\_block\_cipher}, -\function{have\_stream\_cipher}, \function{have\_hash}, and -\function{have\_mac}, passing in the name of the desired algorithm. If Botan -knows about it, the function will return true. - -There are a handful of algorithms which are considered ``sacred'', in that an -application can always expect that they exist, and a distributor or other -end-user should not remove them without considering the possibly serious -consequences. At this time, these are: AES, DES, TripleDES, SHA-1, and HMAC. -This allows a workable fallback strategy for applications. - -One other useful application of this is to remove patented algorithms, for -example if Botan were to be included as part of a commercial Linux -distribution. - -For the most part, applications don't have to really worry about this, simply -because the cases this will be required are fairly rare. Checking for the -availability of patented algorithms like RC5 and IDEA before using them might -be a good idea, though. - -Another advantage of this is that an application can be written to take -advantage of an algorithm which is not currently part of Botan. If it's not -available, one can simply fall back on another algorithm, and when/if it is -added to Botan, the application will start using it automagically. - -\pagebreak -\section{Writing Modules} - -It's a lot simpler to write modules for Botan that it is to write code -in the core library, for several reasons. First, a module can rely on -external libraries and services beyond the base ISO C++ libraries, and -also machine dependent features. Also, the code can be added at -configuration time on the user's end with very little effort (\ie the -code can be distributed separately, and included by the user without -needing to patch any existing source files). - -Each module lives in a subdirectory of the \filename{modules} -directory, which exists at the top-level of the Botan source tree. The -``short name'' of the module is the same as the name of this -directory. The only required file in this directory is -\filename{modinfo.txt}, which contains directives that specify what a -particular module does, what systems it runs on, and so on. Comments -in \filename{modinfo.txt} start with a \verb|#| character and continue -to end of line. - -Recognized directives include: - -\newcommand{\directive}[2]{ - \vskip 4pt - \noindent - \texttt{#1}: #2 -} - -\directive{realname <name>}{Specify that the 'real world' name of this module - is \texttt{<name>}.} - -\directive{note <note>}{Add a note that will be seen by the end-user at -configure time if the module is included into the library.} - -\directive{require\_version <version>}{Require at configure time that -the version of Botan in use be at least \texttt{<version>}.} - -\directive{define <macro>[,<macro>[,...]]}{Cause the macro - \macro{BOTAN\_EXT\_<macro>} (for each instance of \macro{<macro>} - in the directive) to be defined in \filename{build.h}. This should - only be used if the module creates user-visible changes. There is a - set of conventions that should be followed in deciding what to call - this macro (where xxx denotes some descriptive and distinguishing - characteristic of the thing implemented, such as - \macro{ALLOC\_MLOCK} or \macro{MUTEX\_PTHREAD}): +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). -\begin{itemize} -\item Allocator: \macro{ALLOC\_xxx} -\item Compressors: \macro{COMPRESSOR\_xxx} -\item EntropySource: \macro{ENTROPY\_SRC\_xxx} -\item Engines: \macro{ENGINE\_xxx} -\item Mutex: \macro{MUTEX\_xxx} -\item Timer: \macro{TIMER\_xxx} -\end{itemize} -} +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. -\directive{<libs> / </libs>}{This specifies any extra libraries to be -linked in. It is a mapping from OS to library name, for example -\texttt{linux -> rt}, which means that on Linux librt should be linked -in. You can also use ``all'' to force the library to be linked in on -all systems.} +\begin{list}{$\cdot$} + \item Block ciphers: TripleDES or AES in CBC mode with ``PKCS7'' padding. + \item -\directive{<add> / </add>}{Tell the configuration script to add the - files named between these two tags into the source tree. All these - files must exist in the current module directory.} + \item Stream Ciphers: Use any of the recommended block ciphers in CTR mode. -\directive{<ignore> / </ignore>}{Tell the configuration script to - ignore the files named in the main source tree. This is useful, for - example, when replacing a C++ implementation with a pure assembly - version.} + \item Hash functions: SHA-1, SHA-256, SHA-512 -\directive{<replace> / </replace>}{Tell the configuration script to - ignore the file given in the main source tree, and instead use the - one in the module's directory.} + \item MACs: HMAC with any recommended hash function -Additionally, the module file can contain blocks, delimited by the -following pairs: + \item Public Key Encryption: RSA with ``EME1(SHA-1)'' -\texttt{<os> / </os>}, \texttt{<arch> / </arch>}, \texttt{<cc> / </cc>} + \item Public Key Signatures: RSA with EMSA4 and any recommended hash, or DSA + with ``EMSA1(SHA-1)'' -\noindent -For example, putting ``alpha'' and ``ia64'' in a \texttt{<arch>} block will -make the configuration script only allow the module to be compiled on those -architectures. Not having a block means any value is acceptable. + \item Key Agreement: Diffie-Hellman, with ``KDF2(SHA-1)'' +\end{list} -\pagebreak -\section{Compliance with Standards} +\subsection{Compliance with Standards} Botan is/should be compatible with many cryptographic standards, including the following: @@ -3570,42 +3517,7 @@ and \textbf{1363a}. Most of the contents of such are included in the standards mentioned above, in various forms (usually with extra restrictions which 1363 does not impose). -\pagebreak -\section{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: TripleDES or AES in CBC mode with ``PKCS7'' padding. - \item - - \item Stream Ciphers: Use any of the recommended block ciphers in CTR mode. - - \item Hash functions: SHA-1, SHA-256, SHA-512 - - \item MACs: HMAC with any recommended hash function - - \item Public Key Encryption: RSA with ``EME1(SHA-1)'' - - \item Public Key Signatures: RSA with EMSA4 and any recommended hash, or DSA - with ``EMSA1(SHA-1)'' - - \item Key Agreement: Diffie-Hellman, with ``KDF2(SHA-1)'' -\end{list} - -\pagebreak -\section{Algorithms Listing} +\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 @@ -3659,8 +3571,71 @@ match that in SCAN, if it's defined there). \noindent \textbf{MACs:} ``HMAC(HASH)'', ``CMAC(BLOCK)'', ``X9.19-MAC'' -\pagebreak -\section{Support and Further Information} +\subsection{Removing Algorithms} + +You may well want to remove some of Botan's algorithms in order to fit it into +a memory-constrained system, where you're counting the kilobytes. For the most +part, this is trivial to do, and Botan's interface makes it easy for +applications to test for the presence of an algorithm at runtime, so a +well-behaved application can work without any need for porting on such an +version of Botan. + +In some versions of 1.3.x, you can use the 'minimal' module, which removes +large amount of Botan, including most ciphers and hashes (except AES, DES/3DES, +SHA-1, HMAC, RSA, DSA, and Diffie-Hellman), DLIES, EAX and CTS modes, and a few +other odds and ends. You can check for this being the case by seeing if +\macro{BOTAN\_EXT\_MINIMAL} is defined, though for the most part it's better to +use the lookup interface (since you have no way of knowing what exactly the +minimal module might remove from release to release, and certainly not if the +shared object you're linking to has a particular algorithm). This module was +removed just before 1.4.0, as there is a better way to handle all of this in +the new engine code, which is aware of things outside public key algorithms. + +Removing things like the PK signature encoding schemes (EMSA2, EMSA3...) is +somewhat more complicated and not documented here (thought it is actually quite +simple if you know how to do it -- the minimal module shows how). This tutorial +(of sorts) will go through the steps required to compile a version of Botan +without the Blowfish block cipher (which has been included since the first +release of Botan, in the spring of 2001). + +The first step is to remove the files \filename{include/blowfish.h}, +\filename{src/blowfish.cpp}, and \filename{src/blfs\_tab.cpp}, which actually +implement the algorithm. Then minor editing of \filename{src/algolist.cpp} is +required. First, remove the line that includes the Blowfish header +\filename{botan/blowfish.h}. Then look in \function{get\_block\_cipher} for the +code that adds a Blowfish block cipher object to the internal lookup table, and +remove it. Run the configure script, and then \textbf{make} the library. Tada! +Done. + +So how does an application test for such a situation? The first is to simply +try to pass the name ``Blowfish'' to constructor of \type{CBC\_Encryption} or +other Botan \type{Filter}, and catch the resulting exception. This is not +particularly flexible, though. If an application wants to check on the status +of Botan's support for a particular algorithm, it can call some status +functions found in \filename{lookup.h}, called \function{have\_block\_cipher}, +\function{have\_stream\_cipher}, \function{have\_hash}, and +\function{have\_mac}, passing in the name of the desired algorithm. If Botan +knows about it, the function will return true. + +There are a handful of algorithms which are considered ``sacred'', in that an +application can always expect that they exist, and a distributor or other +end-user should not remove them without considering the possibly serious +consequences. At this time, these are: AES, DES, TripleDES, SHA-1, and HMAC. +This allows a workable fallback strategy for applications. + +One other useful application of this is to remove patented algorithms, for +example if Botan were to be included as part of a commercial Linux +distribution. + +For the most part, applications don't have to really worry about this, simply +because the cases this will be required are fairly rare. Checking for the +availability of patented algorithms like RC5 and IDEA before using them might +be a good idea, though. + +Another advantage of this is that an application can be written to take +advantage of an algorithm which is not currently part of Botan. If it's not +available, one can simply fall back on another algorithm, and when/if it is +added to Botan, the application will start using it automagically. \subsection{Compatibility} @@ -3679,6 +3654,9 @@ If you wish maximum portability between different implementations of an algorithm, it's best to stick to strongly defined and well standardized algorithms, TripleDES, AES, HMAC, and SHA-1 all being good examples. +\pagebreak +\section{Support and Further Information} + \subsection{Patents} Some of the algorithms implemented by Botan may be covered by patents in some |