api.tex

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

similar such matters.

The constructor of this object takes a string which specifies various options.
If more than one is used, they should be separated by a space. The options are
listed by order of danger (ie the caution you should have about using the
option), with safest first.

\noindent
\textbf{Option ``seed\_rng''}: If this argument is set, then a ``best effort''
attempt will be made to initialize the random number generator. Even if this
argument is \emph{not} passed, if \filename{/dev/random} is available, it will
be used to seed the RNG (via the \type{File\_EntropySource}).

\noindent
\textbf{Option ``egd\_path=PATH''}: Try to connect to an EGD socket at PATH and
use the output to seed the global RNG. If you do not pass this option, but you
do pass ``seed\_rng'', Botan will attempt to read from an EGD socket at
\filename{/var/run/egd-pool}, which is a pseudo-standard location for the
system's EGD socket.

Be aware that if the process listening on the other side of the socket is
actively hostile, it is possible for it to accept but ignore the connection,
blocking your process.

\noindent
\textbf{Option ``secure\_memory''}: Try to create a more secure allocator type
-- one that either locks allocated memory into RAM, or that memory maps a disk
file that it erases after use. If both are available, it will prefer the memory
mapping mechanism, because locking memory requires root privileges on many
systems.

On systems that don't (currently) have any specialized allocators, like
Windows, this option is ignored.

\noindent
\textbf{Option ``thread\_safe''}: The library should use mutexes for guarding
access to shared resources, such as the memory allocation system. If you pass
the ``thread\_safe'' option, and the initializer can't find a useful mutex
module, it will throw an exception. Thread safety in Botan is basically
untested and it is fairly likely there are problems. If you're going to try
this, be ready to have to send bug reports to the mailing list.

While most things in Botan are already thread-safe at the object level, a few
objects (notably the global RNG, the allocators, and the lookup tables) are
shared between threads for efficiency or security reasons. Access to these
objects are protected using mutexes, and I've tried to ensure things are
locked when they need to be, but I probably am missing some cases.

\noindent
\textbf{Option ``fast\_rng''}: If this option is set, the library will use an
\type{ANSI\_X917\_RNG} object, instead of a somewhat slower \type{Randpool}
object, as the global random number generator. See the section \textit{Random
Number Generators} for more details about what these objects are. Don't pass
this option unless you know what you're doing; there are many cases where the
X9.17 generator does not provide sufficient security (mostly because it has a
fairly small internal state).

\noindent
\textbf{Option ``no\_timers''}: The library should not try to find a high
resolution timer to use. Don't pass this option unless you \emph{really} know
what you're doing.

If you do not create a \type{LibraryInitializer} object, pretty much any Botan
operation will fail, because it will be unable to do basic things like get
memory. Note too, that you should be careful to only create one such object.

\pagebreak

\section{Gotchas}

There are a few things to watch out for to prevent problems when using Botan.

First and primary of these is to \emph{never} allocate any kind of Botan object
globally. The problem is that the constructor for such an object will be called
before the \type{LibraryInitializer} is created, and the constructor will
undoubtedly try to call an object which has not been initialized. If you're
lucky your program will die with an uncaught exception. If you're less lucky,
it will crash from a memory access error. And if you're really unlucky it
\emph{won't} crash, and your program will be in an unknown (but very bad)
state. Generally, global variables are bad news anyway, and I can't think of
many cases where this will cause problems for application code. The library
does have some global objects in it, and a great deal of hackery is involved
making sure everything is created and destroyed at the right time (and in the
right order).

The same rule applies for making sure the destructors of all your Botan objects
are called before the \type{LibraryInitializer} is destroyed. This implies you
can't have static variables that are Botan objects inside functions or
classes. This is kind of inelegant, but rarely a real problem in practice.

Never create a \type{SecureVector} or \type{SecureBuffer} with a type that is
not a basic integer (\type{byte}, \type{u16bit}, \type{u32bit}, \type{u64bit}).
More strongly, if you, as a user of the library, are creating any memory buffer
object that's not a \type{SecureVector<byte>}, you're probably doing something
wrong (I suppose there may be exceptions to this rule, but not many).

Don't include headers you don't have to. Past experience with Botan has shown
that headers get renamed fairly regularly as internal design changes are made,
but this need not affect you, if you follow the ``proper procedures''. Using
the lookup interface defined in \filename{lookup.h} and \filename{look\_pk.h}
will save you a great deal of pain in this regard, as it insulates you against
many such changes.

Enclose your \function{main} with a try block, and catch any
\type{std::exception} throws. This is not strictly required, but if you don't,
and Botan throws an exception, your application would die mysteriously and
without any error message.

Botan's multiple precision integer class (\type{BigInt}) has some of it's low
level functions linked as C. This is to make it easier to write implementations
of them in assembly (as then the name mangling technique used by the compiler
doesn't come into play). These functions are not visible in application space,
but at link time they could cause conflicts, so you should try to avoid naming
functions in your code any name starting with \texttt{bigint\_}.

\pagebreak

\section{The Basic 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 this manual) than for use by applications.

\subsection{Basic Algorithm Abilities}

There are a small handful of functions implemented by most of Botan's
algorithm objects. Among these are:

\noindent
\type{std::string} \function{name}():

Returns a human-readable string of the name of this algorithm. Examples of
names returned are ``Blowfish'' and ``HMAC(MD5)''. You can turn names back into
algorithm objects using the functions in \filename{lookup.h}.

\noindent
\type{void} \function{clear}():

Clear out the algorithm's internal state. A block cipher object will ``forget''
it's key, a hash function will ``forget'' any data put into it, etc.

\noindent
\function{clone}():

This function is central to Botan's name-based interface. The \function{clone}
has many different return types, such as \type{BlockCipher*} and
\type{HashFunction*}, depending on what kind of object it is called on. Note
that unlike Java's clone, this returns a new object in a ``pristine'' state;
that is, operations done on the initial object before calling \function{clone}
do not affect the initial state of the new clone.

Cloned objects can (and should) be deallocated with the C++ \texttt{delete}
operator.

\subsection{Keys}

A \type{SymmetricKey} is an abstraction for a symmetric key, which is
represented as an arbitrary length byte string. The major functions of this
type are it's constructors:

\noindent
\function{SymmetricKey}(\type{u32bit} \arg{length}):

This constructor takes creates a new random key of size \arg{length}.

\noindent
\function{SymmetricKey}(\type{std::string} \arg{str}):

The argument \arg{str} is assumed to be a hex string; it is converted to binary
and stored as the key. Whitespace is ignored.

\noindent
\function{SymmetricKey}(\type{const byte} \arg{input}[], \type{u32bit}
\arg{length}):

This constructor simply copies it's input.

Synonyms for this type include \type{BlockCipher\_Key},
\type{StreamCipher\_Key}, \type{MAC\_Key}, and \type{BlockCipherModeIV}
(they're all exactly the same thing, the different names just makes it clear
what the bytes are being used for).

\subsection{Symmetrically Keyed Algorithms}

Block ciphers, stream ciphers, and MACs all handle keys in pretty much the same
way. To make this similarity explicit, all algorithms of those types are
derived from the \type{SymmetricAlgorithm} base class. This type has three
functions:

\noindent
\type{void} \function{set\_key}(\type{const byte} \arg{key}[], \type{u32bit}
\arg{length}):

Most algorithms only accept keys of certain lengths. If you attempt to call
\function{set\_key} with a key length that is not supported, the exception
\type{Invalid\_Key\_Length} will be thrown. There is also another version of
\function{set\_key} that takes a \type{SymmetricKey} as an argument.

\noindent
\type{bool} \function{valid\_keylength}(\type{u32bit} \arg{length}) const:

This function returns true if a key of the given length will be accepted by
the cipher.

There are also three constant data members of every \type{SymmetricAlgorithm}
object, which specify exactly what limits there are on keys which that object
can accept:

MAXIMUM\_KEYLENGTH: The maximum length of a key. This is at most 32 (256 bits),
even if the algorithm actually supports more.

MINIMUM\_KEYLENGTH: The minimum length of a key. This is at least 1.

KEYLENGTH\_MULTIPLE: The length of the key must be a multiple of this value.

In all cases, \function{set\_key} must be called on an object before any data
processing (encryption, decryption, etc) is done by that object. If this is not
done, the results are undefined -- that is to say, Botan reserves the right in
this situation to do anything from printing a nasty insulting message on the
screen to dumping core.

\subsection{Block Ciphers}

Block ciphers implement the interface \type{BlockCipher}, found in
\filename{base.h}.

\noindent
\type{void} \function{encrypt}(\type{const byte} \arg{in}[BLOCK\_SIZE],
                               \type{byte} \arg{out}[BLOCK\_SIZE]) const

\noindent
\type{void} \function{encrypt}(\type{byte} \arg{block}[BLOCK\_SIZE]) const

These functions apply the block cipher transformation to \arg{in} and place the
result in \arg{out}, or encrypts \arg{block} in place (\arg{in} may be the same
as \arg{out}). BLOCK\_SIZE is a constant member of each class, which specifies
how much data a block cipher can process at one time. Note that BLOCK\_SIZE is
not a static class member, like the old BLOCKSIZE was.

\type{BlockCipher}s have similar functions \function{decrypt}, which perform
the inverse operation.

Block ciphers implement the \type{SymmetricAlgorithm} interface.

\subsection{Stream Ciphers}

Stream ciphers are somewhat different from block ciphers, in that encrypting
data results in changing the internal state of the cipher. Also, you may
encrypt any length of data in one go (in byte amounts).

\noindent
\type{void} \function{encrypt}(\type{const byte} \arg{in}[], \type{byte}
\arg{out}[], \type{u32bit} \arg{length})

\noindent
\type{void} \function{encrypt}(\type{byte} \arg{data}[], \type{u32bit}
\arg{length}):

These functions encrypt the arbitrary length (well, less than 4 gigabyte long)
string \arg{in} and place it into \arg{out}, or encrypts it in place in
\arg{data}. The \function{decrypt} functions look just like
\function{encrypt}.

Stream ciphers implement the \type{SymmetricAlgorithm} interface.

Some stream ciphers support random access to any point in their cipher stream
(currently, the only like this in in Botan is SEAL). For such ciphers, calling
\type{void} \function{seek}(\type{u32bit} \arg{byte}) will change the cipher's
state so that it as if the cipher had been keyed as normal, then encrypted
\arg{byte} -- 1 bytes of data (so the next byte in the cipher stream is byte
number \arg{byte}).

\subsection{Hash Functions / Message Authentication Codes}

Hash functions take their input without producing any output, only producing
anything when all input has already taken place. MACs are very similar, but are
additionally keyed. Both of these are derived from the base class
\type{BufferedComputation}, which has the following functions.