crypt.tex

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

\documentclass[b5paper]{book}
\usepackage{hyperref}
\usepackage{makeidx}
\usepackage{amssymb}
\usepackage{color}
\usepackage{alltt}
\usepackage{graphicx}
\usepackage{layout}
\def\union{\cup}
\def\intersect{\cap}
\def\getsrandom{\stackrel{\rm R}{\gets}}
\def\cross{\times}
\def\cat{\hspace{0.5em} \| \hspace{0.5em}}
\def\catn{$\|$}
\def\divides{\hspace{0.3em} | \hspace{0.3em}}
\def\nequiv{\not\equiv}
\def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}}
\def\lcm{{\rm lcm}}
\def\gcd{{\rm gcd}}
\def\log{{\rm log}}
\def\ord{{\rm ord}}
\def\abs{{\mathit abs}}
\def\rep{{\mathit rep}}
\def\mod{{\mathit\ mod\ }}
\renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})}
\newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor}
\newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil}
\def\Or{{\rm\ or\ }}
\def\And{{\rm\ and\ }}
\def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}}
\def\implies{\Rightarrow}
\def\undefined{{\rm ``undefined"}}
\def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}}
\let\oldphi\phi
\def\phi{\varphi}
\def\Pr{{\rm Pr}}
\newcommand{\str}[1]{{\mathbf{#1}}}
\def\F{{\mathbb F}}
\def\N{{\mathbb N}}
\def\Z{{\mathbb Z}}
\def\R{{\mathbb R}}
\def\C{{\mathbb C}}
\def\Q{{\mathbb Q}}

\def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}}

\def\gap{\vspace{0.5ex}}
\makeindex
\begin{document}
\title{A Tiny Crypto Library, \\ LibTomCrypt \\ Version 0.96}
\author{Tom St Denis \\
\\
[e-mail] \\
http://libtomcrypt.org \\ \\
Phone: [phone]\\
111 Banning Rd \\
Kanata, Ontario \\
K2L 1C3 \\
Canada
}
\maketitle
This text and source code library are both hereby placed in the public domain.  This book has been 
formatted for B5 [176x250] paper using the \LaTeX{} {\em book} macro package.

\vspace{10cm}

\begin{flushright}Open Source.  Open Academia.  Open Minds.

\mbox{ }

Tom St Denis,

Ontario, Canada
\end{flushright}
\newpage
\tableofcontents
\chapter{Introduction}
\section{What is the LibTomCrypt?}
LibTomCrypt is a portable ANSI C cryptographic library that supports symmetric ciphers, one-way hashes, 
pseudo-random number generators, public key cryptography (via RSA,DH or ECC/DH) and a plethora of support 
routines.  It is designed to compile out of the box with the GNU C Compiler (GCC) version 2.95.3 (and higher) 
and with MSVC version 6 in win32.

The library has been successfully tested on quite a few other platforms ranging from the ARM7TDMI in a 
Gameboy Advanced to various PowerPC processors and even the MIPS processor in the PlayStation 2.  Suffice it
to say the code is portable.

The library is designed so new ciphers/hashes/PRNGs can be added at runtime and the existing API (and helper API functions) will 
be able to use the new designs automatically.  There exist self-check functions for each cipher and hash to ensure that
they compile and execute to the published design specifications.  The library also performs extensive parameter error checking
and will give verbose error messages when possible.

Essentially the library saves the time of having to implement the ciphers, hashes, prngs yourself.  Typically implementing
useful cryptography is an error prone business which means anything that can save considerable time and effort is a good
thing.

\subsection{What the library IS for?}

The library typically serves as a basis for other protocols and message formats.  For example, it should be possible to 
take the RSA routines out of this library, apply the appropriate message padding and get PKCS compliant RSA routines.  
Similarly SSL protocols could be formed on top  of the low-level symmetric cipher functions.  The goal of this package is 
to provide these low level core functions in a robust and easy to use fashion.

The library also serves well as a toolkit for applications where they don't need to be OpenPGP, PKCS, etc. compliant.
Included are fully operational public key routines for encryption, decryption, signature generation and verification.  
These routines are fully portable but are not conformant to any known set of standards\footnote{With the exception of 
the RSA code which is based on the PKCS \#1 standards.}.  They are all based on established
number theory and cryptography.  

\subsection{What the library IS NOT for?}

The library is not designed to be in anyway an implementation of the SSL or OpenPGP standards.  The library 
is not designed to be compliant with any known form of API or programming hierarchy.  It is not a port of any other 
library and it is not platform specific (like the MS CSP).  So if you're looking to drop in some buzzword 
compliant crypto library this is not for you.  The library has been written from scratch to provide basic functions as 
well as non-standard higher level functions.  

This is not to say that the library is a ``homebrew'' project.  All of the symmetric ciphers and one-way hash functions
conform to published test vectors.  The public key functions are derived from publicly available material and the majority
of the code has been reviewed by a growing community of developers.

\subsubsection{Why not?}
You may be asking why I didn't choose to go all out and support standards like P1363, PKCS and the whole lot.  The reason
is quite simple too much money gets in the way.  When I tried to access the P1363 draft documents and was denied (it 
requires a password) I realized that they're just a business anyways.  See what happens is a company will sit down and
invent a ``standard''.  Then they try to sell it to as many people as they can.  All of a sudden this ``standard'' is 
everywhere.  Then the standard is updated every so often to keep people dependent.  Then you become RSA.  If people are 
supposed to support these standards they had better make them more accessible.

\section{Why did I write it?}
You may be wondering, ``Tom, why did you write a crypto library.  I already have one.''.  Well the reason falls into
two categories:
\begin{enumerate}
    \item I am too lazy to figure out someone else's API.  I'd rather invent my own simpler API and use that.
    \item It was (still is) good coding practice.
\end{enumerate}

The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc.  I'm trying to write my 
{\bf own} crypto library and hopefully along the way others will appreciate the work.

With this library all core functions (ciphers, hashes, prngs) have the {\bf exact} same prototype definition.  They all load
and store data in a format independent of the platform.  This means if you encrypt with Blowfish on a PPC it should decrypt
on an x86 with zero problems.  The consistent API also means that if you learn how to use blowfish with my library you 
know how to use Safer+ or RC6 or Serpent or ... as well.  With all of the core functions there are central descriptor tables 
that can be used to make a program automatically pick between ciphers, hashes and PRNGs at runtime.  That means your 
application can support all ciphers/hashes/prngs without changing the source code.

\subsection{Modular}
The LibTomCrypt package has also been written to be very modular.  The block ciphers, one-way hashes and
pseudo-random number generators (PRNG) are all used within the API through ``descriptor'' tables which 
are essentially structures with pointers to functions.  While you can still call particular functions
directly (\textit{e.g. sha256\_process()}) this descriptor interface allows the developer to customize their
usage of the library.

For example, consider a hardware platform with a specialized RNG device.  Obviously one would like to tap
that for the PRNG needs within the library (\textit{e.g. making a RSA key}).  All the developer has todo
is write a descriptor and the few support routines required for the device.  After that the rest of the 
API can make use of it without change.  Similiarly imagine a few years down the road when AES2 (\textit{or whatever they call it}) is
invented.  It can be added to the library and used within applications with zero modifications to the
end applications provided they are written properly.

This flexibility within the library means it can be used with any combination of primitive algorithms and 
unlike libraries like OpenSSL is not tied to direct routines.  For instance, in OpenSSL there are CBC block
mode routines for every single cipher.  That means every time you add or remove a cipher from the library
you have to update the associated support code as well.  In LibTomCrypt the associated code (\textit{chaining modes in this case})
are not directly tied to the ciphers.  That is a new cipher can be added to the library by simply providing 
the key setup, ECB decrypt and encrypt and test vector routines.  After that all five chaining mode routines
can make use of the cipher right away.


\section{License}

All of the source code except for the following files have been written by the author or donated to the project
under a public domain license:

\begin{enumerate}
   \item rc2.c
   \item safer.c
\end{enumerate}

`mpi.c'' was originally written by Michael Fromberger ([e-mail]) but has since been replaced with my LibTomMath
library.

``rc2.c'' is based on publicly available code that is not attributed to a person from the given source.  ``safer.c''
was written by Richard De Moliner ([e-mail]) and is public domain.

The project is hereby released as public domain.

\section{Patent Disclosure}

The author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice.  To the best
of the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers.  
They can be removed from a build by simply commenting out the two appropriate lines in the makefile script.  The rest
of the ciphers and hashes are patent free or under patents that have since expired.

The RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations.  This means you can use 
the ciphers you just can't advertise that you are doing so.  

\section{Building the library}

To build the library on a GCC equipped platform simply type ``make'' at your command prompt.  It will build the library
file ``libtomcrypt.a''.  

To install the library copy all of the ``.h'' files into your ``\#include'' path and the single libtomcrypt.a file into 
your library path.

With MSVC you can build the library with ``nmake -f makefile.msvc''.  This will produce a ``tomcrypt.lib'' file which
is the core library.  Copy the header files into your MSVC include path and the library in the lib path (typically
under where VC98 is installed).

\section{Building against the library}

In the recent versions the build steps have changed.  The build options are now stored in ``mycrypt\_custom.h'' and
no longer in the makefile.  If you change a build option in that file you must re-build the library from clean to
ensure the build is intact.  The perl script ``config.pl'' will help setup the custom header and a custom makefile
if you want one (the provided ``makefile'' will work with custom configs).

\section{Thanks}
I would like to give thanks to the following people (in no particular order) for helping me develop this project:
\begin{enumerate}
   \item Richard van de Laarschot
   \item Richard Heathfield
   \item Ajay K. Agrawal
   \item Brian Gladman
   \item Svante Seleborg
   \item Clay Culver
   \item Jason Klapste
   \item Dobes Vandermeer
   \item Daniel Richards
   \item Wayne Scott
   \item Andrew Tyler
   \item Sky Schulz
   \item Christopher Imes
\end{enumerate}

\chapter{The Application Programming Interface (API)}
\section{Introduction}
\index{CRYPT\_ERROR} \index{CRYPT\_OK}

In general the API is very simple to memorize and use.  Most of the functions return either {\bf void} or {\bf int}.  Functions
that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful or one of the many error codes 
if it failed.  Certain functions that return int will return $-1$ to indicate an error.  These functions will be explicitly
commented upon.  When a function does return a CRYPT error code it can be translated into a string with

\index{error\_to\_string()}
\begin{verbatim}
const char *error_to_string(int err);
\end{verbatim}

An example of handling an error is:
\begin{verbatim}
void somefunc(void)
{
   int err;
   
   /* call a cryptographic function */
   if ((err = some_crypto_function(...)) != CRYPT_OK) {
      printf("A crypto error occured, %s\n", error_to_string(err));
      /* perform error handling */
   }
   /* continue on if no error occured */
}
\end{verbatim}

There is no initialization routine for the library and for the most part the code is thread safe.  The only thread
related issue is if you use the same symmetric cipher, hash or public key state data in multiple threads.  Normally
that is not an issue.

To include the prototypes for ``LibTomCrypt.a'' into your own program simply include ``mycrypt.h'' like so:
\begin{verbatim}
#include <mycrypt.h>
int main(void) {
    return 0;
}
\end{verbatim}

The header file ``mycrypt.h'' also includes ``stdio.h'', ``string.h'', ``stdlib.h'', ``time.h'', ``ctype.h'' and ``mpi.h''
(the bignum library routines).

\section{Macros}

There are a few helper macros to make the coding process a bit easier.  The first set are related to loading and storing