api.tex

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

This section contains descriptions of every \type{Filter} included in Botan.
Note that modules which provide \type{Filter}s are documented elsewhere --
these \type{Filter}s are available on any installation of Botan.

\subsubsection{Keyed Filters}

A few sections ago, it was mentioned that Pipe can process multiple messages,
treating each of them exactly the same. Well, that was a bit of a lie. There
are some algorithms (in particular, block ciphers not in ECB mode, and all
stream ciphers) that change their state as data is put through them.

Naturally, you might well want to reset the keys or (in the case of block
cipher modes) IVs used by such filters, so multiple messages can be processed
using completely different keys, or new IVs, or new keys and IVs, or whatever.
And in fact, even for a MAC or an ECB block cipher, you might well want to
change the key used from message to message.

Enter \type{Keyed\_Filter}. It's a base class of any filter that is keyed:
block cipher modes, stream ciphers, MACs, whatever. It has two functions,
\function{reset\_key} and \function{reset\_iv}. Calling \function{reset\_key}
will, naturally, reset the key used by the algorithm. Reseting the IV only
makes sense in certain algorithms -- calling \function{reset\_iv} will cause an
exception if the filter in question doesn't support it.

Here's a slightly edited fragment of code from the \filename{rsa\_dec} example
application. For the complete source, look in \filename{doc/examples} in the
distribution.

\begin{verbatim}
   Keyed_Filter *cast, *hmac;
   Pipe pipe(new Base64_Decoder,
             // Note the assignments to the cast and hmac variables
             cast = new CBC_Decryption("CAST-128", "PKCS7", cast_key, iv),
             new Fork(
                0, // Read the section 'Fork' to understand this
                new Chain(
                   hmac = new MAC_Filter("HMAC(SHA-1)", mac_key, 12),
                   new Base64_Encoder
                   )
                )
      );
   pipe.start_msg();
   [use pipe for a while, decrypt some stuff, derive new keys and IVs]
   pipe.end_msg();

   cast->reset_key(cast_key2);
   cast->reset_iv(iv2);
   hmac->reset_key(mac_key2);

   pipe.start_msg();
   [use pipe for some other things]
   pipe.end_msg();
\end{verbatim}

There is a requirement to using \type{Keyed\_Filter} which you must follow. If
you call \function{reset\_key} or \function{reset\_iv}, you must do so while
the Pipe is ``unlocked''. This refers to the times when no messages are being
processed by Pipe -- either before Pipe's \function{start\_msg} is called, or
after \function{end\_msg} is called (and no new call to \function{start\_msg}
has happened yet). Doing otherwise will result in undefined behavior, probably
silently getting invalid output.

\pagebreak

\subsubsection{Basic Wrappers}

Stream ciphers, hash functions, and MACs don't need anything special when it
comes to filters. Stream ciphers take their input, encrypt it, and send it
along to the next \type{Filter}. Hash functions and MACs both take their input
and produce no output until \function{end\_msg()} is called, at which time they
complete the hash or MAC and send that as output.

These \type{Filter}s take a string naming the type to be used. If for some
reason you name something that doesn't exist, an exception will be thrown.
Generally speaking you can use any obvious name here, like ``SHA-1'', ``ARC4'',
``HMAC(SHA-1)'', or even really odd recursive things like
``EMAC(Lion(SHA-1,SEAL(8),1024))'', just as long as it's well formed and in the
end everything resolves to the correct type.

\noindent
\function{StreamCipher\_Filter}(\type{std::string} \arg{cipher},
                                \type{const StreamCipher\_Key\&} \arg{key})

Pretty basic; key \arg{cipher} with \arg{key}, anything passed through the
filter is encrypted with the stream cipher.

\noindent
\function{Hash\_Filter}(\type{std::string} \arg{hash},
                        \type{u32bit} \arg{outlength}):

This type hashes it's input with \arg{hash}. When \function{end\_msg} is called
on the owning \type{Pipe}, the hash is completed and the digest is sent on to
the next thing in the pipe. The argument \arg{outlength} specifies how much of
the output of the hash will be passed along to the next filter when
\function{end\_msg} is called. By default, it will pass the entire hash.

\noindent
\function{MAC\_Filter}(\type{std::string} \arg{mac},
                       \type{const MAC\_Key\&} \arg{key},
                       \type{u32bit} \arg{outlength}):

The constructor for a \type{MAC\_Filter} takes a key, used in calculating the
MAC, and a length parameter, which has semantics exactly the same as the one
passed to \type{Hash\_Filter}s constructor.

These filters can be found in \filename{filters.h}.

\pagebreak

\subsubsection{Cipher Modes}

For block ciphers, the situation is more complicated. Because ECB mode is
dangerous (a message may be easily altered without detection and similar
plaintext encrypts to similar ciphertext), block ciphers must usually be used
in a different mode. The modes provided with Botan are CBC, CTS, CFB, OFB, and
CTR. They are presented in \filename{cbc.h}, \filename{cts.h},
\filename{cfb.h}, \filename{ofb.h}, and \filename{ctr.h}.

Only their constructors are interesting; other than that they are just like any
other filter, and are used like any other discussed in this documentation. Each
one takes a \type{std::string} as the first argument. This names the cipher to
be used to encryption/decryption. The constructors to the decryption filters
are identical to that of the encryption modes (the types are named
\type{MODENAME\_Decryption}).

\noindent

\parskip 0pt
\noindent
\function{CBC\_Encryption}(\type{std::string} \arg{cipher},
                           \type{std::string} \arg{padding},

\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 
                           \type{const BlockCipher\_Key\&} \arg{key},
                           \type{const BlockCipherModeIV\&} \arg{iv}):
\parskip 5pt

This is quite simple: a key, of a length suitable for the cipher, and an IV,
which is the size of the cipher block (if it is not an exception will be
thrown).

The second string, \arg{padding}, specifies what kind of padding to use at the
end of the block. The three currently defined padding methods are ``PKCS7'',
``OneAndZeros'', and ``NoPadding''. If ``NoPadding'' is used, then the object
will throw an exception if it's input is not an exact multiple of the cipher's
block size -- don't use it unless you have to.

Some padding methods can only work with block ciphers that have certain block
sizes (for example, ``PKCS7''), while others (such as ``OneAndZeros'') will
work for any size block cipher. If the chosen block cipher/padding method pair
cannot work together, a \type{Invalid\_Block\_Size} exception will be thrown by
the constructor.

Additionally, a \type{DecodingError} exception can be thrown when
\function{end\_msg()} is called on the decrypting CBC filter, if the input data
was not formatted correctly.

\noindent
\function{CTS\_Encryption}(\type{std::string} \arg{cipher},
                           \type{const BlockCipher\_Key\&} \arg{key},
                           \type{const BlockCipherModeIV\&} \arg{iv}):

CTS (Cipher Text Stealing) mode is the same as CBC except for the last 2
blocks. It uses a neat little trick to make it so that the ciphertext is always
the same size as the plaintext. It does not use any external padding method, so
that argument isn't needed.

\noindent
\parskip=0pt
\function{CFB\_Encryption}(\type{std::string} \arg{cipher},
                           \type{const BlockCipher\_Key\&} \arg{key},
                           \type{const BlockCipherModeIV\&} \arg{iv},

\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 
                           \type{u32bit} \arg{feedback}):
\parskip=5pt

This is similar to CBC, but it takes an (optional) additional argument, the
size of the feedback (it will default to the full blocksize of the cipher being
used). This value is given in bytes, and can range from 1 to BLOCK\_SIZE. If
the \arg{feedback} is not a valid amount, \type{Invalid\_Argument} will be
thrown. The ciphertext will always be the same size of the plaintext.

\noindent
\function{OFB}(\type{std::string} \arg{cipher},
               \type{const BlockCipher\_Key\&} \arg{key},
               \type{const BlockCipherModeIV\&} \arg{iv}):

This is the usual OFB mode. Variable feedback sizes are not supported, as it
has been shown that they are insecure. The \type{CTR} mode is a variant of
\type{OFB}, whose constructor takes the same arguments. Remember that a block
cipher operating in either OFB or counter modes is like a stream cipher, and
thus you must never encrypt two messages with the same key without changing the
IV. Since OFB and CTR are their own inverses, there is no need for separate
encryption and decryption classes.

\noindent
\function{ECB\_Encryption}(\type{std::string} \arg{cipher},
                           \type{const BlockCipher\_Key\&} \arg{key})

Don't use this mode unless you know what you are doing. For the vast majority
of applications, it is \emph{insecure}. You can find the \type{ECB\_Encryption}
and \type{ECB\_Decryption} filters in \filename{ecb.h}.

\pagebreak

\subsubsection{PK Filters}

There are four classes in this category, \type{PK\_Encryptor\_Filter},
\type{PK\_Decryptor\_Filter}, \type{PK\_Signer\_Filter}, and
\type{PK\_Verifier\_Filter}. Each takes a pointer to an object of the
appropriate type (\type{PK\_Encryptor}, \type{PK\_Decryptor}, etc) which is
deleted by the destructor. These classes are found in \filename{pk\_filts.h}.

Three of these, for encryption, decryption, and signing are pretty much
identical conceptually. Each of them buffers it's input until the end of the
message is marked with a call to the \function{end\_msg} function. Then they
encrypt, decrypt, or sign their input and send the output (the ciphertext, the
plaintext, or the signature) into the next filter.

Signature verification works a little differently, because it needs to know
what the signature is in order to check it. You can either pass this in along
with the constructor, or call the function \function{set\_signature} -- with
this second method, you need to keep a pointer to the filter around so you can
send it this command. In either case, after \function{end\_msg} is called, it
will try to verify the signature (if the signature has not been set by either
method, an exception will be thrown here). It will then send a single byte onto
the next filter -- a 1 or a 0, which specifies whether the signature verified
or not (respectively).

For more information about PK algorithms (including creating the appropriate
objects to pass to the constructors), read the section ``Public Key
Cryptography'' in this manual.

\subsubsection{Encoders}

Often you want your data to be in some form of text (for sending over channels
which aren't 8-bit clean, printing it, etc). The filters \type{Hex\_Encoder}
and \type{Base64\_Encoder} will convert arbitrary binary data into hex or
base64 formats. Not surprisingly, you can use \type{Hex\_Decoder} and
\type{Base64\_Decoder} to convert it back into it's original form.

Both of the encoders can take a few options about how the data should be
formatted (all of which have defaults). The first is a \type{bool} which simply
says if the encoder should insert line breaks. This defaults to
false. Line breaks don't matter either way to the decoder, but it makes the
output a bit more appealing to the human eye, and a few transport mechanisms
(notably some email systems) limit the maximum line length.

The second encoder option is an integer specifying how long such lines will be
(obviously this will be ignored if line-breaking isn't being used). The default
tends to be in the range of 60-80 characters, but is not specified exactly. If
you want a specific value, set it. Otherwise the default should be fine.

Lastly, \type{Hex\_Encoder} takes an argument of type \type{Case}, which can be
\type{Uppercase} or \type{Lowercase} (default is \type{Uppercase}). This
specifies what case the characters A-F should be output as. The base64 encoder
has no such option, because it uses both upper and lower case letters for it's
output.

You can find the declarations for these types in \filename{hex.h} and
\filename{base64.h}.

\pagebreak

\section{Random Number Generators}

The random number generators provided in Botan are meant for creating keys,
IVs, padding, nonces, and anything else which requires 'random' data. It is
important to remember that the output of these classes will vary, even if they
are supplied with exactly the same seed (ie, two Randpool objects with similar
initial states will not produce the same output).

To ensure good quality output, you need to seed the RNG with truly 'random'
data, such as timing data from hardware. Preferably, you should use an
\type{EntropySource} (see below).

To add entropy