api.tex

含有多种公开密钥算法、多种块加密、多种数据流加密、多种HASH函数、多种CheckSum校验、多种MAC校验等几十种加密算法的程序

\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 API Documentation}
\author{Jack Lloyd ([e-mail])}
\date{August 25, 2002}

\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}}

\begin{document}

\maketitle

\tableofcontents

\parskip=5pt
\pagebreak

\section{Introduction}

Botan is a C++ library which attempts to provide the most common cryptographic
algorithms in an easy to use and portable package. Currently it runs on a wide
variety of systems, using numerous different compilers and on many different
CPU architectures.

The base library is written in ISO C++, so it can be ported with minimal fuss,
but Botan also supports a modules system, which allows system dependent code
to be compiled into the library for use by application code.

While you are reading this, you may want to refer to the files
\filename{base.h} and \filename{pipe.h}. These files contain the classes that
form the basic interface for the library.

\subsection{Basic Conventions}

With a few exceptions declarations in the library are contained within the
namespace \texttt{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 thus it would be often be convenient to use
them without the \texttt{Botan::} prefix. You can, by \texttt{using} the
namespace \texttt{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 as
\filename{botan/headername.h} in your actual code.

Prior to version 0.9.1, Botan was known as OpenCL. You can use the name OpenCL
wherever Botan is used (for header files, namespaces, macros, etc). This is
not recommended for new code.

\subsection{Targets}

Botan's primary targets (system-wise) are 32 and 64 bit systems with at least a
few hundred kilobytes of memory. Generally, given the choice between optimizing
for 32 bit systems and 64 bit systems, Botan chooses 64 bits, simply on the
theory that where performance really matters (like servers), people are using
64 bit machines. But performance on 32 bit systems is also quite good.

Nowadays, smaller systems such as handhelds, phones, and smart cards, are also
capable of using Botan. For very low-end machines, such as 8 bit smart cards
with only a few tens of kilobytes of RAM and RAM, Botan is too large, even in
stripped down form, to be useful. Botan has been used on a Compaq iPaq handheld
with no problems.

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 simply ask Botan if the algorithm
exists, and if Botan says yes, ask the library to give them such an object for
that algorithm.

\pagebreak

\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
and is not.

First, let's cover the major strengths. Botan:

\begin{list}{*}
  \item Is written in a (fairly) clean object-oriented style, and the usual
        API works in terms of reasonably high-level abstractions.
  \item

  \item Supports a huge variety of algorithms, including most of the major
        public key algorithms and standards (such as IEEE 1363 and PKCS \#1)

  \item Supports a name-based lookup scheme, so you can get ahold of any
        algorithm on the fly.

  \item You can easily extend much of the system at run or (application)
        compile time.

  \item Works well with a wide variety of compilers, operating systems, and
        CPUs, and more all the time.

  \item Is the only open source crypto library (that I know of) that has
        support for memory allocation techniques that prevent an attacker from
        reading swap in an attempt to gain access to keys or other
        secrets. In fact two different such methods are supported.

  \item Has (optional) support for Zlib and Bzip2 compression/decompression
        integrated completely into the system -- it only takes a line or two of
        code to add compression to your application.
\end{list}

\noindent
And the major downsides and deficiencies are:

\begin{list}{*}
  \item It's written in C++. If your application isn't, Botan is probably
        going to be more pain than it's worth.
  \item

  \item While efficiency is a major goal, Botan is not (currently) as fast as
        say, OpenSSL. This is mostly due to the lack of assembly optimizations
        (crypto is one of the last few areas where assembly really does make
        sense), and partly from using non-optimal algorithms in some places.

        Both of these issues will be dealt with within the next 6-9 months,
        probably sooner.

  \item Doesn't support higher-level protocols and formats like SSL or OpenPGP.
        This will eventually be available as separate packages. Of course you
        can write it yourself (and I would be happy to help with that in any
        way I can). Some work is beginning on TLS support, but it's a ways out
        still.

  \item Doesn't (currently) support elliptic curves.

  \item Doesn't (currently) support any very high-level 'envelope' style
        processing.
\end{list}

\pagebreak

\section{Building The Library}

These are the basic steps for compiling Botan on a Unix or Unix-like system:

\begin{verbatim}
   $ ./configure.pl CC-OS-CPU
   $ make
   $ make check # optional, but recommended
   # make install
\end{verbatim}

The \filename{configure.pl} script is written in Perl; you'll need at least
version 5.005 to run the script. To get the list of values for \verb|CC|,
\verb|OS|, and \verb|CPU| that \filename{configure.pl} supports, run it with
the ``\verb|--help|'' option.

The \verb|make install| target has a default directory in which it will install
Botan (on Unix, it's \verb|/usr/local|). You can override this by changing the
value of the INSTALLROOT variable, like so:

\verb|make INSTALLROOT=/some/path install|

On Unix, the makefile has to decide who should own the files once they are
installed. By default, it uses \texttt{root:root}, but on some systems (for
example, MacOS X), there is no \texttt{root} group. Also, if you don't have
root access on the system you will want them to be installed owned by something
other than root (like yourself). You can override the defaults in a similar
manner to the \texttt{INSTALLROOT}. Here's an example:

\verb|make OWNER=lloyd GROUP=users INSTALLROOT=$HOME/binaries install|

The script tries to guess what kind of makefile to generate, but it might guess
wrong, so 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.

You can put basically anything reasonable for CPU: the script knows about a
large number of different architectures, their sub-models, and common aliases
for them. The script does not display all the possibilities in it's help
message because there are simply too many entries (if you're curious about what
exactly is available, you can look at the \verb|%ARCH|, \verb|%ARCH_ALIAS|, and
\verb|%SUBMODEL_ALIAS| hashes at the start of the script).

Note that you should only select the 64-bit version of a CPU (like ``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. For
example, gcc-solaris-sparc64 will not work unless you're running a 64-bit
Solaris kernel (for 32-bit Solaris running on an UltraSPARC system, you want
gcc-solaris-sparc32-v9). You may or may not have to install 64-bit versions of
libc and related system libraries as well.

The script also knows about the various extension modules available. You can
enable one or more with the option ``\verb|--modules=MOD|'', where \verb|MOD|
is some name that identifies the extension (or a comma separated list of them).
Modules provide additional capabilities such making a Zlib
compressor/decompressor system available, or replacing the implementation of
\function{system\_clock} with \function{gettimeofday} on some Unices. You
should enable any extensions which makes sense for your system. There is also
the concept of a ``module set'', essentially a set of modules which can be
referred to by a single name. At the time of this writing, the only available
module set is called 'unix', and includes about half a dozen modules which
should run on most, if not all, recent Unix systems. You can add a module set
with ``\verb|--module-set=MODSET|''.

Note that not all OSes or CPUs have specific support. If the CPU architecture
of your system isn't supported by \filename{configure.pl}, use
'generic'. This setting disables machine-specific optimization
flags. Similarly, setting OS to 'generic' disables things which depend greatly
on OS support (specifically, shared libraries).

However, it's impossible to guess which options to give to a system compiler.
Thus, if you want to compile Botan with a compiler which
\filename{configure.pl} does not support, the script will have to be updated.
Preferably, mail the man pages (or similar documentation) for the C and C++
compilers and the system linker to the author, or download the Botan-config
package from the Botan web site, and do it yourself.

\pagebreak

\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{config.h} are macros which are defined if one or
more extensions are available. All of them begin with \verb|BOTAN_EXT_|. For
example, if \verb|BOTAN_EXT_BZIP2| is defined, then an application using
Botan can include \filename{<botan/bzip2.h>} and use the Bzip2 filters.

\texttt{DEFAULT\_BUFFERSIZE}: 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. If you're
particularly concerned about memory usage (for example, for a small embedded
system with little memory), drop it down to 256 or so.

\texttt{VECTOR\_OVER\_ALLOCATE}: The memory container \type{SecureVector} will
overallocate requests by this amount (in elements). In several areas of the
library, we grow a vector fairly often. By overallocating 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.

\texttt{MP\_WORD\_BITS}: This macro controls the size of the words used for
calculations with the MPI implementation (called \type{BigInt}). You can choose
8, 16, or 32 bits, with 32 being the default. In general, I can't imagine a
situation where this is truly useful to change, but it's helpful for testing
purposes. Keep in mind that changing this breaks binary compatibility. In
general, halving the size of the word also halves the speed of \type{BigInt}
operations.

\pagebreak

\section{Initializing the Library}

The library needs to have various things done to it in order for it to work
correctly. To make sure this is done properly, you should create a
\type{LibraryInitializer} object at the start of your main() function, before
you start using any part of Botan. The initializer does things like
initializing the memory allocation system, setting up the algorithm lookup
tables, finding out if there is a high resolution timer available to use, and