crypt.tex

最新版本的加密解密算法库

32/64-bit words in little/big endian format.  The macros are:

\index{STORE32L} \index{STORE64L} \index{LOAD32L} \index{LOAD64L}
\index{STORE32H} \index{STORE64H} \index{LOAD32H} \index{LOAD64H} \index{BSWAP}
\begin{small}
\begin{center}
\begin{tabular}{|c|c|c|}
     \hline STORE32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 3]$ \\
     \hline STORE64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 7]$ \\
     \hline LOAD32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[0 \ldots 3] \to x$ \\
     \hline LOAD64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[0 \ldots 7] \to x$ \\
     \hline STORE32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[3 \ldots 0]$ \\
     \hline STORE64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[7 \ldots 0]$ \\
     \hline LOAD32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[3 \ldots 0] \to x$ \\
     \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\
     \hline BSWAP(x) & {\bf unsigned long} x & Swaps the byte order of x. \\
     \hline
\end{tabular}
\end{center}
\end{small}

There are 32-bit cyclic rotations as well:
\index{ROL} \index{ROR}
\begin{center}
\begin{tabular}{|c|c|c|}
     \hline ROL(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y$ \\
     \hline ROR(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y$ \\
     \hline
\end{tabular}
\end{center}

\section{Functions with Variable Length Output}
Certain functions such as (for example) ``rsa\_export()'' give an output that is variable length.  To prevent buffer overflows you
must pass it the length of the buffer\footnote{Extensive error checking is not in place but it will be in future releases so it is a good idea to follow through with these guidelines.} where
the output will be stored.  For example:
\begin{small}
\begin{verbatim}
#include <mycrypt.h>
int main(void) {
    rsa_key key;
    unsigned char buffer[1024];
    unsigned long x;
    int err;

    /* ... Make up the RSA key somehow */

    /* lets export the key, set x to the size of the output buffer */
    x = sizeof(buffer);
    if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) {
       printf("Export error: %s\n", error_to_string(err));
       return -1;
    }
    
    /* if rsa_export() was successful then x will have the size of the output */
    printf("RSA exported key takes %d bytes\n", x);

    /* ... do something with the buffer */

    return 0;
}
\end{verbatim}
\end{small}
In the above example if the size of the RSA public key was more than 1024 bytes this function would not store anything in
either ``buffer'' or ``x'' and simply return an error code.  If the function suceeds it stores the length of the output
back into ``x'' so that the calling application will know how many bytes used.

\section{Functions that need a PRNG}
Certain functions such as ``rsa\_make\_key()'' require a PRNG.  These functions do not setup the PRNG themselves so it is 
the responsibility of the calling function to initialize the PRNG before calling them.

\section{Functions that use Arrays of Octets}
Most functions require inputs that are arrays of the data type ``unsigned char''.  Whether it is a symmetric key, IV
for a chaining mode or public key packet it is assumed that regardless of the actual size of ``unsigned char'' only the
lower eight bits contain data.  For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine
you must pass it in (a pointer to) an array of 32 ``unsigned char'' variables.  Certain routines 
(such as SAFER+) take special care to work properly on platforms where an ``unsigned char'' is not eight bits.

For the purposes of this library the term ``byte'' will refer to an octet or eight bit word.  Typically an array of
type ``byte'' will be synonymous with an array of type ``unsigned char''.

\chapter{Symmetric Block Ciphers}
\section{Core Functions}

Libtomcrypt provides several block ciphers all in a plain vanilla ECB block mode.  Its important to first note that you 
should never use the ECB modes directly to encrypt data.  Instead you should use the ECB functions to make a chaining mode
or use one of the provided chaining modes.  All of the ciphers are written as ECB interfaces since it allows the rest of
the API to grow in a modular fashion.

All ciphers store their scheduled keys in a single data type called ``symmetric\_key''.  This allows all ciphers to 
have the same prototype and store their keys as  naturally as possible.  All ciphers provide five visible functions which
are (given that XXX is the name of the cipher):
\index{Cipher Setup}
\begin{verbatim}
int XXX_setup(const unsigned char *key, int keylen, int rounds,
              symmetric_key *skey);
\end{verbatim}

The XXX\_setup() routine will setup the cipher to be used with a given number of rounds and a given key length (in bytes).
The number of rounds can be set to zero to use the default, which is generally a good idea.

If the function returns successfully the variable ``skey'' will have a scheduled key stored in it.  Its important to note
that you should only used this scheduled key with the intended cipher.  For example, if you call 
``blowfish\_setup()'' do not pass the scheduled key onto ``rc5\_ecb\_encrypt()''.  All setup functions do not allocate 
memory off the heap so when you are done with a key you can simply discard it (e.g. they can be on the stack).

To encrypt or decrypt a block in ECB mode there are these two functions:
\index{Cipher Encrypt} \index{Cipher Decrypt}
\begin{verbatim}
void XXX_ecb_encrypt(const unsigned char *pt, unsigned char *ct,
                     symmetric_key *skey);

void XXX_ecb_decrypt(const unsigned char *ct, unsigned char *pt,
                     symmetric_key *skey);
\end{verbatim}
These two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on
which cipher you are using.} and store the result where you want it.  It is possible that the input and output buffer are 
the same buffer.  For the encrypt function ``pt''\footnote{pt stands for plaintext.} is the input and ``ct'' is the output.
For the decryption function its the opposite.  To test a particular cipher against test vectors\footnote{As published in their design papers.} call: \index{Cipher Testing}
\begin{verbatim}
int XXX_test(void);
\end{verbatim}
This function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is 
based upon.  Finally for each cipher there is a function which will help find a desired key size:
\begin{verbatim}
int XXX_keysize(int *keysize);
\end{verbatim}
Essentially it will round the input keysize in ``keysize'' down to the next appropriate key size.  This function
return {\bf CRYPT\_OK} if the key size specified is acceptable.  For example:
\begin{small}
\begin{verbatim}
#include <mycrypt.h>
int main(void)
{
   int keysize, err;

   /* now given a 20 byte key what keysize does Twofish want to use? */
   keysize = 20;
   if ((err = twofish_keysize(&keysize)) != CRYPT_OK) {
      printf("Error getting key size: %s\n", error_to_string(err));
      return -1;
   }
   printf("Twofish suggested a key size of %d\n", keysize);
   return 0;
}
\end{verbatim}
\end{small}
This should indicate a keysize of sixteen bytes is suggested.  An example snippet that encodes a block with 
Blowfish in ECB mode is below.

\begin{small}
\begin{verbatim}
#include <mycrypt.h>
int main(void)
{ 
   unsigned char pt[8], ct[8], key[8];
   symmetric_key skey;
   int err;

   /* ... key is loaded appropriately in ``key'' ... */
   /* ... load a block of plaintext in ``pt'' ... */

   /* schedule the key */
   if ((err = blowfish_setup(key,     /* the key we will use */
                               8,     /* key is 8 bytes (64-bits) long */
                               0,     /* 0 == use default # of rounds */
                           &skey)     /* where to put the scheduled key */
       ) != CRYPT_OK) {
      printf("Setup error: %s\n", error_to_string(err));
      return -1;
   }

   /* encrypt the block */
   blowfish_ecb_encrypt(pt,             /* encrypt this 8-byte array */
                        ct,             /* store encrypted data here */ 
                        &skey);         /* our previously scheduled key */

   /* decrypt the block */
   blowfish_ecb_decrypt(ct,             /* decrypt this 8-byte array */
                        pt,             /* store decrypted data here */
                        &skey);         /* our previously scheduled key */

   return 0;
}
\end{verbatim}
\end{small}

\section{Key Sizes and Number of Rounds}
\index{Symmetric Keys}
As a general rule of thumb do not use symmetric keys under 80 bits if you can.  Only a few of the ciphers support smaller
keys (mainly for test vectors anyways).  Ideally your application should be making at least 256 bit keys.  This is not
because you're supposed to be paranoid.  Its because if your PRNG has a bias of any sort the more bits the better.  For
example, if you have $\mbox{Pr}\left[X = 1\right] = {1 \over 2} \pm \gamma$ where $\vert \gamma \vert > 0$ then the
total amount of entropy in N bits is $N \cdot -log_2\left ({1 \over 2} + \vert \gamma \vert \right)$.  So if $\gamma$
were $0.25$ (a severe bias) a 256-bit string would have about 106 bits of entropy whereas a 128-bit string would have
only 53 bits of entropy.

The number of rounds of most ciphers is not an option you can change.  Only RC5 allows you to change the number of
rounds.  By passing zero as the number of rounds all ciphers will use their default number of rounds.  Generally the
ciphers are configured such that the default number of rounds provide adequate security for the given block size.

\section{The Cipher Descriptors}
\index{Cipher Descriptor}
To facilitate automatic routines an array of cipher descriptors is provided in the array ``cipher\_descriptor''.  An element
of this array has the following format:

\begin{verbatim}
struct _cipher_descriptor {
   char *name;
   unsigned long min_key_length, max_key_length, 
                 block_length, default_rounds;
   int  (*setup)      (const unsigned char *key, int keylength, 
                       int num_rounds, symmetric_key *skey);
   void (*ecb_encrypt)(const unsigned char *pt, unsigned char *ct, 
                       symmetric_key *key);
   void (*ecb_decrypt)(const unsigned char *ct, unsigned char *pt,
                       symmetric_key *key);
   int  (*test)       (void);
   int  (*keysize)    (int *desired_keysize);
};
\end{verbatim}

Where ``name'' is the lower case ASCII version of the name.  The fields ``min\_key\_length'', ``max\_key\_length'' and
``block\_length'' are all the number of bytes not bits.  As a good rule of thumb it is assumed that the cipher supports
the min and max key lengths but not always everything in between.  The ``default\_rounds'' field is the default number
of rounds that will be used.

The remaining fields are all pointers to the core functions for each cipher.  The end of the cipher\_descriptor array is
marked when ``name'' equals {\bf NULL}.

As of this release the current cipher\_descriptors elements are

\index{Cipher descriptor table}
\begin{small}
\begin{center}
\begin{tabular}{|c|c|c|c|c|c|}
     \hline Name & Descriptor Name & Block Size & Key Range & Rounds \\
     \hline Blowfish & blowfish\_desc & 8 & 8 $\ldots$ 56 & 16 \\
     \hline X-Tea & xtea\_desc & 8 & 16 & 32 \\
     \hline RC2 & rc2\_desc & 8 & 8 $\ldots$ 128 & 16 \\
     \hline RC5-32/12/b & rc5\_desc & 8 & 8 $\ldots$ 128 & 12 $\ldots$ 24 \\
     \hline RC6-32/20/b & rc6\_desc & 16 & 8 $\ldots$ 128 & 20 \\
     \hline SAFER+ & saferp\_desc &16 & 16, 24, 32 & 8, 12, 16 \\
     \hline Safer K64   & safer\_k64\_desc & 8 & 8 & 6 $\ldots$ 13 \\
     \hline Safer SK64  & safer\_sk64\_desc & 8 & 8 & 6 $\ldots$ 13 \\
     \hline Safer K128  & safer\_k128\_desc & 8 & 16 & 6 $\ldots$ 13 \\
     \hline Safer SK128 & safer\_sk128\_desc & 8 & 16 & 6 $\ldots$ 13 \\
     \hline AES & aes\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\
                & aes\_enc\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\
     \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\
     \hline DES & des\_desc & 8 & 7 & 16 \\
     \hline 3DES (EDE mode) & des3\_desc & 8 & 21 & 16 \\
     \hline CAST5 (CAST-128) & cast5\_desc & 8 & 5 $\ldots$ 16 & 12, 16 \\
     \hline Noekeon & noekeon\_desc & 16 & 16 & 16 \\
     \hline Skipjack & skipjack\_desc & 8 & 10 & 32 \\
     \hline
\end{tabular}
\end{center}
\end{small}

\subsection{Notes}
\begin{small}
\begin{enumerate}
\item
For AES (also known as Rijndael) there are four descriptors which complicate issues a little.  The descriptors 
rijndael\_desc and rijndael\_enc\_desc provide the cipher named ``rijndael''.  The descriptors aes\_desc and 
aes\_enc\_desc provide the cipher name ``aes''.  Functionally both ``rijndael'' and ``aes'' are the same cipher.  The
only difference is when you call find\_cipher() you have to pass the correct name.  The cipher descriptors with ``enc'' 
in the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine
and tables.  The decryption and self--test function pointers of both ``encrypt only'' descriptors are set to \textbf{NULL} and 
should not be called.

The ``encrypt only'' descriptors are useful for applications that only use the encryption function of the cipher.  Algorithms such
as EAX, PMAC and OMAC only require the encryption function.  So far this ``encrypt only'' functionality has only been implemented for
Rijndael as it makes the most sense for this cipher.

\item
For the 64-bit SAFER famliy of ciphers (e.g K64, SK64, K128, SK128) the ecb\_encrypt() and ecb\_decrypt()
functions are the same.  So if you want to use those functions directly just call safer\_ecb\_encrypt()
or safer\_ecb\_decrypt() respectively.

\item
Note that for ``DES'' and ``3DES'' they use 8 and 24 byte keys but only 7 and 21 [respectively] bytes of the keys are in