dropbear: crypt.tex comparison

comparison crypt.tex @ 3:7faae8f46238 libtomcrypt-orig

Branch renaming

author	Matt Johnston <matt@ucc.asn.au>
date	Mon, 31 May 2004 18:25:41 +0000
parents
children	6362d3854bb4

comparison

equal deleted inserted replaced

--1:000000000000
+:7faae8f46238
+\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.95}
+\author{Tom St Denis \\
+\\
+[email protected] \\
+http://libtomcrypt.org \\ \\
+Phone: 1-613-836-3160\\
+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.  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 ([email protected]) 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 ([email protected]) 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
+\begin{verbatim}
+const char *error_to_string(int errno);
+\end{verbatim}
+An example of handling an error is:
+\begin{verbatim}
+void somefunc(void)
+{
+int errno;
+/* call a cryptographic function */
+if ((errno = some_crypto_function(...)) != CRYPT_OK) {
+printf("A crypto error occured, %s\n", error_to_string(errno));
+/* 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
+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 errno;
+/* ... Make up the RSA key somehow */
+/* lets export the key, set x to the size of the output buffer */
+x = sizeof(buffer);
+if ((errno = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) {
+printf("Export error: %s\n", error_to_string(errno));
+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, errno;
+/* now given a 20 byte key what keysize does Twofish want to use? */
+keysize = 20;
+if ((errno = twofish_keysize(&keysize)) != CRYPT_OK) {
+printf("Error getting key size: %s\n", error_to_string(errno));
+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 errno;
+/* ... key is loaded appropriately in ``key'' ... */
+/* ... load a block of plaintext in ``pt'' ... */
+/* schedule the key */
+if ((errno = blowfish_setup(key, 8, 0, &skey)) != CRYPT_OK) {
+printf("Setup error: %s\n", error_to_string(errno));
+return -1;
+}
+/* encrypt the block */
+blowfish_ecb_encrypt(pt, ct, &skey);
+/* decrypt the block */
+blowfish_ecb_decrypt(ct, pt, &skey);
+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
+\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 \\
+\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}
+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.
+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
+fact used for the purposes of encryption.  My suggestion is just to use random 8/24 byte keys instead of trying to make a 8/24
+byte string from the real 7/21 byte key.
+Note that ``Twofish'' has additional configuration options that take place at build time.  These options are found in
+the file ``mycrypt\_cfg.h''.  The first option is ``TWOFISH\_SMALL'' which when defined will force the Twofish code
+to not pre-compute the Twofish ``$g(X)$'' function as a set of four $8 \times 32$ s-boxes.  This means that a scheduled
+key will require less ram but the resulting cipher will be slower.  The second option is ``TWOFISH\_TABLES'' which when
+defined will force the Twofish code to use pre-computed tables for the two s-boxes $q_0, q_1$ as well as the multiplication
+by the polynomials 5B and EF used in the MDS multiplication.  As a result the code is faster and slightly larger.  The
+speed increase is useful when ``TWOFISH\_SMALL'' is defined since the s-boxes and MDS multiply form the heart of the
+Twofish round function.
+\begin{small}
+\begin{center}
+\begin{tabular}{|l|l|l|}
+\hline TWOFISH\_SMALL & TWOFISH\_TABLES & Speed and Memory (per key) \\
+\hline undefined & undefined & Very fast, 4.2KB of ram. \\
+\hline undefined & defined & As above, faster keysetup, larger code (1KB more). \\
+\hline defined & undefined & Very slow, 0.2KB of ram. \\
+\hline defined & defined & Somewhat faster, 0.2KB of ram, larger code. \\
+\hline
+\end{tabular}
+\end{center}
+\end{small}
+To work with the cipher\_descriptor array there is a function:
+\begin{verbatim}
+int find_cipher(char *name)
+\end{verbatim}
+Which will search for a given name in the array.  It returns negative one if the cipher is not found, otherwise it returns
+the location in the array where the cipher was found.  For example, to indirectly setup Blowfish you can also use:
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+unsigned char key[8];
+symmetric_key skey;
+int errno;
+/* you must register a cipher before you use it */
+if (register_cipher(&blowfish_desc)) == -1) {
+printf("Unable to register Blowfish cipher.");
+return -1;
+}
+/* generic call to function (assuming the key in key[] was already setup) */
+if ((errno = cipher_descriptor[find_cipher("blowfish")].setup(key, 8, 0, &skey)) != CRYPT_OK) {
+printf("Error setting up Blowfish: %s\n", error_to_string(errno));
+return -1;
+}
+/* ... use cipher ... */
+}
+\end{verbatim}
+\end{small}
+A good safety would be to check the return value of ``find\_cipher()'' before accessing the desired function.  In order
+to use a cipher with the descriptor table you must register it first using:
+\begin{verbatim}
+int register_cipher(const struct _cipher_descriptor *cipher);
+\end{verbatim}
+Which accepts a pointer to a descriptor and returns the index into the global descriptor table.  If an error occurs such
+as there is no more room (it can have 32 ciphers at most) it will return {\bf{-1}}.  If you try to add the same cipher more
+than once it will just return the index of the first copy.  To remove a cipher call:
+\begin{verbatim}
+int unregister_cipher(const struct _cipher_descriptor *cipher);
+\end{verbatim}
+Which returns {\bf CRYPT\_OK} if it removes it otherwise it returns {\bf CRYPT\_ERROR}.  Consider:
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+int errno;
+/* register the cipher */
+if (register_cipher(&rijndael_desc) == -1) {
+printf("Error registering Rijndael\n");
+return -1;
+}
+/* use Rijndael */
+/* remove it */
+if ((errno = unregister_cipher(&rijndael_desc)) != CRYPT_OK) {
+printf("Error removing Rijndael: %s\n", error_to_string(errno));
+return -1;
+}
+return 0;
+}
+\end{verbatim}
+\end{small}
+This snippet is a small program that registers only Rijndael only.
+\section{Symmetric Modes of Operations}
+\subsection{Background}
+A typical symmetric block cipher can be used in chaining modes to effectively encrypt messages larger than the block
+size of the cipher.  Given a key $k$, a plaintext $P$ and a cipher $E$ we shall denote the encryption of the block
+$P$ under the key $k$ as $E_k(P)$.  In some modes there exists an initial vector denoted as $C_{-1}$.
+\subsubsection{ECB Mode}
+ECB or Electronic Codebook Mode is the simplest method to use.  It is given as:
+\begin{equation}
+C_i = E_k(P_i)
+\end{equation}
+This mode is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more
+than once.
+\subsubsection{CBC Mode}
+CBC or Cipher Block Chaining mode is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers.
+It is given as:
+\begin{equation}
+C_i = E_k(P_i \oplus C_{i - 1})
+\end{equation}
+It is important that the initial vector be unique and preferably random for each message encrypted under the same key.
+\subsubsection{CTR Mode}
+CTR or Counter Mode is a mode which only uses the encryption function of the cipher.  Given a initial vector which is
+treated as a large binary counter the CTR mode is given as:
+\begin{eqnarray}
+C_{-1} = C_{-1} + 1\mbox{ }(\mbox{mod }2^W) \nonumber \\
+C_i = P_i \oplus E_k(C_{-1})
+\end{eqnarray}
+Where $W$ is the size of a block in bits (e.g. 64 for Blowfish).  As long as the initial vector is random for each message
+encrypted under the same key replay and swap attacks are infeasible.  CTR mode may look simple but it is as secure
+as the block cipher is under a chosen plaintext attack (provided the initial vector is unique).
+\subsubsection{CFB Mode}
+CFB or Ciphertext Feedback Mode is a mode akin to CBC.  It is given as:
+\begin{eqnarray}
+C_i = P_i \oplus C_{-1} \nonumber \\
+C_{-1} = E_k(C_i)
+\end{eqnarray}
+Note that in this library the output feedback width is equal to the size of the block cipher.  That is this mode is used
+to encrypt whole blocks at a time.  However, the library will buffer data allowing the user to encrypt or decrypt partial
+blocks without a delay.  When this mode is first setup it will initially encrypt the initial vector as required.
+\subsubsection{OFB Mode}
+OFB or Output Feedback Mode is a mode akin to CBC as well.  It is given as:
+\begin{eqnarray}
+C_{-1} = E_k(C_{-1}) \nonumber \\
+C_i = P_i \oplus C_{-1}
+\end{eqnarray}
+Like the CFB mode the output width in CFB mode is the same as the width of the block cipher.  OFB mode will also
+buffer the output which will allow you to encrypt or decrypt partial blocks without delay.
+\subsection{Choice of Mode}
+My personal preference is for the CTR mode since it has several key benefits:
+\begin{enumerate}
+\item No short cycles which is possible in the OFB and CFB modes.
+\item Provably as secure as the block cipher being used under a chosen plaintext attack.
+\item Technically does not require the decryption routine of the cipher.
+\item Allows random access to the plaintext.
+\item Allows the encryption of block sizes that are not equal to the size of the block cipher.
+\end{enumerate}
+The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size.  They
+accomplish this by buffering the data required to complete a block.  This allows you to encrypt or decrypt any size
+block of memory with either of the three modes.
+The ECB and CBC modes process blocks of the same size as the cipher at a time.  Therefore they are less flexible than the
+other modes.
+\subsection{Implementation}
+\index{CBC Mode} \index{CTR Mode}
+\index{OFB Mode} \index{CFB Mode}
+The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages.  Assuming the mode
+you want is XXX there is a structure called ``symmetric\_XXX'' that will contain the information required to
+use that mode.  They have identical setup routines (except ECB mode for obvious reasons):
+\begin{verbatim}
+int XXX_start(int cipher, const unsigned char *IV,
+const unsigned char *key, int keylen,
+int num_rounds, symmetric_XXX *XXX);
+int ecb_start(int cipher, const unsigned char *key, int keylen,
+int num_rounds, symmetric_ECB *ecb);
+\end{verbatim}
+In each case ``cipher'' is the index into the cipher\_descriptor array of the cipher you want to use.  The ``IV'' value is
+the initialization vector to be used with the cipher.  You must fill the IV yourself and it is assumed they are the same
+length as the block size\footnote{In otherwords the size of a block of plaintext for the cipher, e.g. 8 for DES, 16 for AES, etc.}
+of the cipher you choose.  It is important that the IV  be random for each unique message you want to encrypt.  The
+parameters ``key'', ``keylen'' and ``num\_rounds'' are the same as in the XXX\_setup() function call.  The final parameter
+is a pointer to the structure you want to hold the information for the mode of operation.
+Both routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise they return an error code.  To
+actually encrypt or decrypt the following routines are provided:
+\begin{verbatim}
+int XXX_encrypt(const unsigned char *pt, unsigned char *ct,
+symmetric_XXX *XXX);
+int XXX_decrypt(const unsigned char *ct, unsigned char *pt,
+symmetric_XXX *XXX);
+int YYY_encrypt(const unsigned char *pt, unsigned char *ct,
+unsigned long len, symmetric_YYY *YYY);
+int YYY_decrypt(const unsigned char *ct, unsigned char *pt,
+unsigned long len, symmetric_YYY *YYY);
+\end{verbatim}
+Where ``XXX'' is one of (ecb, cbc) and ``YYY'' is one of (ctr, ofb, cfb).  In the CTR, OFB and CFB cases ``len'' is the
+size of the buffer (as number of chars) to encrypt or decrypt.  The CTR, OFB and CFB modes are order sensitive but not
+chunk sensitive.  That is you can encrypt ``ABCDEF'' in three calls like ``AB'', ``CD'', ``EF'' or two like ``ABCDE'' and ``F''
+and end up with the same ciphertext.  However, encrypting ``ABC'' and ``DABC'' will result in different ciphertexts.  All
+five of the modes will return {\bf CRYPT\_OK} on success from the encrypt or decrypt functions.
+To decrypt in either mode you simply perform the setup like before (recall you have to fetch the IV value you used)
+and use the decrypt routine on all of the blocks.  When you are done working with either mode you should wipe the
+memory (using ``zeromem()'') to help prevent the key from leaking.  For example:
+\newpage
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+unsigned char key[16], IV[16], buffer[512];
+symmetric_CTR ctr;
+int x, errno;
+/* register twofish first */
+if (register_cipher(&twofish_desc) == -1) {
+printf("Error registering cipher.\n");
+return -1;
+}
+/* somehow fill out key and IV */
+/* start up CTR mode */
+if ((errno = ctr_start(find_cipher("twofish"), IV, key, 16, 0, &ctr)) != CRYPT_OK) {
+printf("ctr_start error: %s\n", error_to_string(errno));
+return -1;
+}
+/* somehow fill buffer than encrypt it */
+if ((errno = ctr_encrypt(buffer, buffer, sizeof(buffer), &ctr)) != CRYPT_OK) {
+printf("ctr_encrypt error: %s\n", error_to_string(errno));
+return -1;
+}
+/* make use of ciphertext... */
+/* clear up and return */
+zeromem(key, sizeof(key));
+zeromem(&ctr, sizeof(ctr));
+return 0;
+}
+\end{verbatim}
+\end{small}
+\section{Encrypt and Authenticate Modes}
+\subsection{EAX Mode}
+LibTomCrypt provides support for a mode called EAX\footnote{See
+M. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the
+way it was intended to be used.
+First a short description of what EAX mode is before I explain how to use it.  EAX is a mode that requires a cipher,
+CTR and OMAC support and provides encryption and authentication.  It is initialized with a random ``nonce'' that can
+be shared publicly as well as a ``header'' which can be fixed and public as well as a random secret symmetric key.
+The ``header'' data is meant to be meta-data associated with a stream that isn't private (e.g. protocol messages).  It can
+be added at anytime during an EAX stream and is part of the authentication tag.  That is, changes in the meta-data can
+be detected by an invalid output tag.
+The mode can then process plaintext producing ciphertext as well as compute a partial checksum.  The actual checksum
+called a ``tag'' is only emitted when the message is finished.  In the interim though the user can process any arbitrary
+sized message block to send to the recipient as ciphertext.  This makes the EAX mode especially suited for streaming modes
+of operation.
+The mode is initialized with the following function.
+\begin{verbatim}
+int eax_init(eax_state *eax, int cipher,
+const unsigned char *key, unsigned long keylen,
+const unsigned char *nonce, unsigned long noncelen,
+const unsigned char *header, unsigned long headerlen);
+\end{verbatim}
+Where ``eax'' is the EAX state.  ``cipher'' is the index of the desired cipher in the descriptor table.
+``key'' is the shared secret symmetric key of length ``keylen''.  ``nonce'' is the random public string of
+length ``noncelen''.  ``header'' is the random (or fixed or \textbf{NULL}) header for the message of length
+``headerlen''.
+When this function completes ``eax'' will be initialized such that you can now either have data decrypted or
+encrypted in EAX mode.  Note that if ``headerlen'' is zero you may pass ``header'' as \textbf{NULL}.  It will still
+initialize the EAX ``H'' value to the correct value.
+To encrypt or decrypt data in a streaming mode use the following.
+\begin{verbatim}
+int eax_encrypt(eax_state *eax, const unsigned char *pt,
+unsigned char *ct, unsigned long length);
+int eax_decrypt(eax_state *eax, const unsigned char *ct,
+unsigned char *pt, unsigned long length);
+\end{verbatim}
+The function ``eax\_encrypt'' will encrypt the bytes in ``pt'' of ``length'' bytes and store the ciphertext in
+``ct''.  Note that ``ct'' and ``pt'' may be the same region in memory.   This function will also send the ciphertext
+through the OMAC function.  The function ``eax\_decrypt'' decrypts ``ct'' and stores it in ``pt''.  This also allows
+``pt'' and ``ct'' to be the same region in memory.
+Note that both of these functions allow you to send the data in any granularity but the order is important.  While
+the eax\_init() function allows you to add initial header data to the stream you can also add header data during the
+EAX stream with the following.
+Also note that you cannot both encrypt or decrypt with the same ``eax'' context.  For bi-directional communication you
+will need to initialize two EAX contexts (preferably with different headers and nonces).
+\begin{verbatim}
+int eax_addheader(eax_state *eax,
+const unsigned char *header, unsigned long length);
+\end{verbatim}
+This will add the ``length'' bytes from ``header'' to the given ``eax'' stream.  Once the message is finished the
+``tag'' (checksum) may be computed with the following function.
+\begin{verbatim}
+int eax_done(eax_state *eax,
+unsigned char *tag, unsigned long *taglen);
+\end{verbatim}
+This will terminate the EAX state ``eax'' and store upto ``taglen'' bytes of the message tag in ``tag''.  The function
+then stores how many bytes of the tag were written out back into ``taglen''.
+The EAX mode code can be tested to ensure it matches the test vectors by calling the following function.
+\begin{verbatim}
+int eax_test(void);
+\end{verbatim}
+This requires that the AES (or Rijndael) block cipher be registered with the cipher\_descriptor table first.
+\subsection{OCB Mode}
+LibTomCrypt provides support for a mode called OCB\footnote{See
+P. Rogaway, M. Bellare, J. Black, T. Krovetz, ``OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption''.}
+in a mode somewhat similar to as it was meant to be used.
+OCB is an encryption protocol that simultaneously provides authentication.  It is slightly faster to use than EAX mode
+but is less flexible.  Let's review how to initialize an OCB context.
+\begin{verbatim}
+int ocb_init(ocb_state *ocb, int cipher,
+const unsigned char *key, unsigned long keylen,
+const unsigned char *nonce);
+\end{verbatim}
+This will initialize the ``ocb'' context using cipher descriptor ``cipher''.  It will use a ``key'' of length ``keylen''
+and the random ``nonce''.  Note that ``nonce'' must be a random (public) string the same length as the block ciphers
+block size (e.g. 16 for AES).
+This mode has no ``Associated Data'' like EAX mode does which means you cannot authenticate metadata along with the stream.
+To encrypt or decrypt data use the following.
+\begin{verbatim}
+int ocb_encrypt(ocb_state *ocb, const unsigned char *pt, unsigned char *ct);
+int ocb_decrypt(ocb_state *ocb, const unsigned char *ct, unsigned char *pt);
+\end{verbatim}
+This will encrypt (or decrypt for the latter) a fixed length of data from ``pt'' to ``ct'' (vice versa for the latter).
+They assume that ``pt'' and ``ct'' are the same size as the block cipher's block size.  Note that you cannot call
+both functions given a single ``ocb'' state.  For bi-directional communication you will have to initialize two ``ocb''
+states (with different nonces).  Also ``pt'' and ``ct'' may point to the same location in memory.
+When you are finished encrypting the message you call the following function to compute the tag.
+\begin{verbatim}
+int ocb_done_encrypt(ocb_state *ocb,
+const unsigned char *pt, unsigned long ptlen,
+unsigned char *ct,
+unsigned char *tag, unsigned long *taglen);
+\end{verbatim}
+This will terminate an encrypt stream ``ocb''.  If you have trailing bytes of plaintext that will not complete a block
+you can pass them here.  This will also encrypt the ``ptlen'' bytes in ``pt'' and store them in ``ct''.  It will also
+store upto ``taglen'' bytes of the tag into ``tag''.
+Note that ``ptlen'' must be less than or equal to the block size of block cipher chosen.  Also note that if you have
+an input message equal to the length of the block size then you pass the data here (not to ocb\_encrypt()) only.
+To terminate a decrypt stream and compared the tag you call the following.
+\begin{verbatim}
+int ocb_done_decrypt(ocb_state *ocb,
+const unsigned char *ct,  unsigned long ctlen,
+unsigned char *pt,
+const unsigned char *tag, unsigned long taglen,
+int *res);
+\end{verbatim}
+Similarly to the previous function you can pass trailing message bytes into this function.  This will compute the
+tag of the message (internally) and then compare it against the ``taglen'' bytes of ``tag'' provided.  By default
+``res'' is set to zero.  If all ``taglen'' bytes of ``tag'' can be verified then ``res'' is set to one (authenticated
+message).
+To make life simpler the following two functions are provided for memory bound OCB.
+\begin{verbatim}
+int ocb_encrypt_authenticate_memory(int cipher,
+const unsigned char *key,    unsigned long keylen,
+const unsigned char *nonce,
+const unsigned char *pt,     unsigned long ptlen,
+unsigned char *ct,
+unsigned char *tag,    unsigned long *taglen);
+\end{verbatim}
+This will OCB encrypt the message ``pt'' of length ``ptlen'' and store the ciphertext in ``ct''.  The length ``ptlen''
+can be any arbitrary length.
+\begin{verbatim}
+int ocb_decrypt_verify_memory(int cipher,
+const unsigned char *key,    unsigned long keylen,
+const unsigned char *nonce,
+const unsigned char *ct,     unsigned long ctlen,
+unsigned char *pt,
+const unsigned char *tag,    unsigned long taglen,
+int           *res);
+\end{verbatim}
+Similarly this will OCB decrypt and compare the internally computed tag against the tag provided. ``res'' is set
+appropriately.
+\chapter{One-Way Cryptographic Hash Functions}
+\section{Core Functions}
+Like the ciphers there are hash core functions and a universal data type to hold the hash state called ``hash\_state''.
+To initialize hash XXX (where XXX is the name) call:
+\index{Hash Functions}
+\begin{verbatim}
+void XXX_init(hash_state *md);
+\end{verbatim}
+This simply sets up the hash to the default state governed by the specifications of the hash.  To add data to the
+message being hashed call:
+\begin{verbatim}
+int XXX_process(hash_state *md, const unsigned char *in, unsigned long len);
+\end{verbatim}
+Essentially all hash messages are virtually infinitely\footnote{Most hashes are limited to $2^{64}$ bits or 2,305,843,009,213,693,952 bytes.} long message which
+are buffered.  The data can be passed in any sized chunks as long as the order of the bytes are the same the message digest
+(hash output) will be the same.  For example, this means that:
+\begin{verbatim}
+md5_process(&md, "hello ", 6);
+md5_process(&md, "world", 5);
+\end{verbatim}
+Will produce the same message digest as the single call:
+\index{Message Digest}
+\begin{verbatim}
+md5_process(&md, "hello world", 11);
+\end{verbatim}
+To finally get the message digest (the hash) call:
+\begin{verbatim}
+int XXX_done(hash_state *md,
+unsigned char *out);
+\end{verbatim}
+This function will finish up the hash and store the result in the ``out'' array.  You must ensure that ``out'' is long
+enough for the hash in question.  Often hashes are used to get keys for symmetric ciphers so the ``XXX\_done()'' functions
+will wipe the ``md'' variable before returning automatically.
+To test a hash function call:
+\begin{verbatim}
+int XXX_test(void);
+\end{verbatim}
+This will return {\bf CRYPTO\_OK} if the hash matches the test vectors, otherwise it returns an error code.  An
+example snippet that hashes a message with md5 is given below.
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+hash_state md;
+unsigned char *in = "hello world", out[16];
+/* setup the hash */
+md5_init(&md);
+/* add the message */
+md5_process(&md, in, strlen(in));
+/* get the hash in out[0..15] */
+md5_done(&md, out);
+return 0;
+}
+\end{verbatim}
+\end{small}
+\section{Hash Descriptors}
+\index{Hash Descriptors}
+Like the set of ciphers the set of hashes have descriptors too.  They are stored in an array called ``hash\_descriptor'' and
+are defined by:
+\begin{verbatim}
+struct _hash_descriptor {
+char *name;
+unsigned long hashsize;    /* digest output size in bytes  */
+unsigned long blocksize;   /* the block size the hash uses */
+void (*init)   (hash_state *);
+int  (*process)(hash_state *, const unsigned char *, unsigned long);
+int  (*done)   (hash_state *, unsigned char *);
+int  (*test)   (void);
+};
+\end{verbatim}
+Similarly ``name'' is the name of the hash function in ASCII (all lowercase).  ``hashsize'' is the size of the digest output
+in bytes.  The remaining fields are pointers to the functions that do the respective tasks.  There is a function to
+search the array as well called ``int find\_hash(char *name)''.  It returns -1 if the hash is not found, otherwise the
+position in the descriptor table of the hash.
+You can use the table to indirectly call a hash function that is chosen at runtime.  For example:
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+unsigned char buffer[100], hash[MAXBLOCKSIZE];
+int idx, x;
+hash_state md;
+/* register hashes .... */
+if (register_hash(&md5_desc) == -1) {
+printf("Error registering MD5.\n");
+return -1;
+}
+/* register other hashes ... */
+/* prompt for name and strip newline */
+printf("Enter hash name: \n");
+fgets(buffer, sizeof(buffer), stdin);
+buffer[strlen(buffer) - 1] = 0;
+/* get hash index */
+idx = find_hash(buffer);
+if (idx == -1) {
+printf("Invalid hash name!\n");
+return -1;
+}
+/* hash input until blank line */
+hash_descriptor[idx].init(&md);
+while (fgets(buffer, sizeof(buffer), stdin) != NULL)
+hash_descriptor[idx].process(&md, buffer, strlen(buffer));
+hash_descriptor[idx].done(&md, hash);
+/* dump to screen */
+for (x = 0; x < hash_descriptor[idx].hashsize; x++)
+printf("%02x ", hash[x]);
+printf("\n");
+return 0;
+}
+\end{verbatim}
+\end{small}
+Note the usage of ``MAXBLOCKSIZE''.  In Libtomcrypt no symmetric block, key or hash digest is larger than MAXBLOCKSIZE in
+length.  This provides a simple size you can set your automatic arrays to that will not get overrun.
+There are three helper functions as well:
+\index{hash\_memory()} \index{hash\_file()}
+\begin{verbatim}
+int hash_memory(int hash, const unsigned char *data,
+unsigned long len, unsigned char *dst,
+unsigned long *outlen);
+int hash_file(int hash, const char *fname,
+unsigned char *dst,
+unsigned long *outlen);
+int hash_filehandle(int hash, FILE *in,
+unsigned char *dst, unsigned long *outlen);
+\end{verbatim}
+The ``hash'' parameter is the location in the descriptor table of the hash (\textit{e.g. the return of find\_hash()}).
+The ``*outlen'' variable is used to keep track of the output size.  You
+must set it to the size of your output buffer before calling the functions.  When they complete succesfully they store
+the length of the message digest back in it.  The functions are otherwise straightforward.  The ``hash\_filehandle''
+function assumes that ``in'' is an file handle opened in binary mode.  It will hash to the end of file and not reset
+the file position when finished.
+To perform the above hash with md5 the following code could be used:
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+int idx, errno;
+unsigned long len;
+unsigned char out[MAXBLOCKSIZE];
+/* register the hash */
+if (register_hash(&md5_desc) == -1) {
+printf("Error registering MD5.\n");
+return -1;
+}
+/* get the index of the hash  */
+idx = find_hash("md5");
+/* call the hash */
+len = sizeof(out);
+if ((errno = hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) {
+printf("Error hashing data: %s\n", error_to_string(errno));
+return -1;
+}
+return 0;
+}
+\end{verbatim}
+\end{small}
+The following hashes are provided as of this release:
+\begin{center}
+\begin{tabular}{|c|c|c|}
+\hline Name & Descriptor Name & Size of Message Digest (bytes) \\
+\hline WHIRLPOOL & whirlpool\_desc & 64 \\
+\hline SHA-512 & sha512\_desc & 64 \\
+\hline SHA-384 & sha384\_desc & 48 \\
+\hline SHA-256 & sha256\_desc & 32 \\
+\hline SHA-224 & sha224\_desc & 28 \\
+\hline TIGER-192 & tiger\_desc & 24 \\
+\hline SHA-1 & sha1\_desc & 20 \\
+\hline RIPEMD-160 & rmd160\_desc & 20 \\
+\hline RIPEMD-128 & rmd128\_desc & 16 \\
+\hline MD5 & md5\_desc & 16 \\
+\hline MD4 & md4\_desc & 16 \\
+\hline MD2 & md2\_desc & 16 \\
+\hline
+\end{tabular}
+\end{center}
+Similar to the cipher descriptor table you must register your hash algorithms before you can use them.  These functions
+work exactly like those of the cipher registration code.  The functions are:
+\begin{verbatim}
+int register_hash(const struct _hash_descriptor *hash);
+int unregister_hash(const struct _hash_descriptor *hash);
+\end{verbatim}
+\subsection{Notice}
+It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes.
+These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators
+(e.g. Yarrow).
+The other hashes such as the SHA-1, SHA-2 (that includes SHA-512, SHA-384 and SHA-256) and TIGER-192 are still considered secure
+for all purposes you would normally use a hash for.
+\chapter{Message Authentication Codes}
+\section{HMAC Protocol}
+Thanks to Dobes Vandermeer the library now includes support for hash based message authenication codes or HMAC for short.  An HMAC
+of a message is a keyed authenication code that only the owner of a private symmetric key will be able to verify.  The purpose is
+to allow an owner of a private symmetric key to produce an HMAC on a message then later verify if it is correct.  Any impostor or
+eavesdropper will not be able to verify the authenticity of a message.
+The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key
+and its length.  The key is much like a key you would pass to a cipher.  That is, it is simply an array of octets stored in
+chars.  The initialization routine is:
+\begin{verbatim}
+int hmac_init(hmac_state *hmac, int hash,
+const unsigned char *key, unsigned long keylen);
+\end{verbatim}
+The ``hmac'' parameter is the state for the HMAC code.  ``hash'' is the index into the descriptor table of the hash you want
+to use to authenticate the message.  ``key'' is the pointer to the array of chars that make up the key.  ``keylen'' is the
+length (in octets) of the key you want to use to authenticate the message.  To send octets of a message through the HMAC system you must use the following function:
+\begin{verbatim}
+int hmac_process(hmac_state *hmac, const unsigned char *buf,
+unsigned long len);
+\end{verbatim}
+``hmac'' is the HMAC state you are working with. ``buf'' is the array of octets to send into the HMAC process.  ``len'' is the
+number of octets to process.  Like the hash process routines you can send the data in arbitrarly sized chunks. When you
+are finished with the HMAC process you must call the following function to get the HMAC code:
+\begin{verbatim}
+int hmac_done(hmac_state *hmac, unsigned char *hashOut,
+unsigned long *outlen);
+\end{verbatim}
+``hmac'' is the HMAC state you are working with.  ``hashOut'' is the array of octets where the HMAC code should be stored.  You must
+set ``outlen'' to the size of the destination buffer before calling this function.  It is updated with the length of the HMAC code
+produced (depending on which hash was picked).  If ``outlen'' is less than the size of the message digest (and ultimately
+the HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first ``outlen'' bytes).
+There are two  utility functions provided to make using HMACs easier todo.  They accept the key and information about the
+message (file pointer, address in memory) and produce the HMAC result in one shot.  These are useful if you want to avoid
+calling the three step process yourself.
+\begin{verbatim}
+int hmac_memory(int hash, const unsigned char *key, unsigned long keylen,
+const unsigned char *data, unsigned long len,
+unsigned char *dst, unsigned long *dstlen);
+\end{verbatim}
+This will produce an HMAC code for the array of octets in ``data'' of length ``len''.  The index into the hash descriptor
+table must be provided in ``hash''.  It uses the key from ``key'' with a key length of ``keylen''.
+The result is stored in the array of octets ``dst'' and the length in ``dstlen''.  The value of ``dstlen'' must be set
+to the size of the destination buffer before calling this function.  Similarly for files there is the  following function:
+\begin{verbatim}
+int hmac_file(int hash, const char *fname, const unsigned char *key,
+unsigned long keylen,
+unsigned char *dst, unsigned long *dstlen);
+\end{verbatim}
+``hash'' is the index into the hash descriptor table of the hash you want to use.  ``fname'' is the filename to process.
+``key'' is the array of octets to use as the key of length ``keylen''.  ``dst'' is the array of octets where the
+result should be stored.
+To test if the HMAC code is working there is the following function:
+\begin{verbatim}
+int hmac_test(void);
+\end{verbatim}
+Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code.  Some example code for using the
+HMAC system is given below.
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+int idx, errno;
+hmac_state hmac;
+unsigned char key[16], dst[MAXBLOCKSIZE];
+unsigned long dstlen;
+/* register SHA-1 */
+if (register_hash(&sha1_desc) == -1) {
+printf("Error registering SHA1\n");
+return -1;
+}
+/* get index of SHA1 in hash descriptor table */
+idx = find_hash("sha1");
+/* we would make up our symmetric key in "key[]" here */
+/* start the HMAC */
+if ((errno = hmac_init(&hmac, idx, key, 16)) != CRYPT_OK) {
+printf("Error setting up hmac: %s\n", error_to_string(errno));
+return -1;
+}
+/* process a few octets */
+if((errno = hmac_process(&hmac, "hello", 5) != CRYPT_OK) {
+printf("Error processing hmac: %s\n", error_to_string(errno));
+return -1;
+}
+/* get result (presumably to use it somehow...) */
+dstlen = sizeof(dst);
+if ((errno = hmac_done(&hmac, dst, &dstlen)) != CRYPT_OK) {
+printf("Error finishing hmac: %s\n", error_to_string(errno));
+return -1;
+}
+printf("The hmac is %lu bytes long\n", dstlen);
+/* return */
+return 0;
+}
+\end{verbatim}
+\end{small}
+\section{OMAC Support}
+OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an
+algorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES.  From an API
+standpoint the OMAC routines work much like the HMAC routines do.  Instead in this case a cipher is used instead of a hash.
+To start an OMAC state you call
+\begin{verbatim}
+int omac_init(omac_state *omac, int cipher,
+const unsigned char *key, unsigned long keylen);
+\end{verbatim}
+The ``omac'' variable is the state for the OMAC algorithm.  ``cipher'' is the index into the cipher\_descriptor table
+of the cipher\footnote{The cipher must have a 64 or 128 bit block size.  Such as CAST5, Blowfish, DES, AES, Twofish, etc.} you
+wish to use.  ``key'' and ``keylen'' are the keys used to authenticate the data.
+To send data through the algorithm call
+\begin{verbatim}
+int omac_process(omac_state *state,
+const unsigned char *buf, unsigned long len);
+\end{verbatim}
+This will send ``len'' bytes from ``buf'' through the active OMAC state ``state''.  Returns \textbf{CRYPT\_OK} if the
+function succeeds.  The function is not sensitive to the granularity of the data.  For example,
+\begin{verbatim}
+omac_process(&mystate, "hello",  5);
+omac_process(&mystate, " world", 6);
+\end{verbatim}
+Would produce the same result as,
+\begin{verbatim}
+omac_process(&mystate, "hello world",  11);
+\end{verbatim}
+When you are done processing the message you can call the following to compute the message tag.
+\begin{verbatim}
+int omac_done(omac_state *state,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+Which will terminate the OMAC and output the \textit{tag} (MAC) to ``out''.  Note that unlike the HMAC and other code
+``outlen'' can be smaller than the default MAC size (for instance AES would make a 16-byte tag).  Part of the OMAC
+specification states that the output may be truncated.  So if you pass in $outlen = 5$ and use AES as your cipher than
+the output MAC code will only be five bytes long.  If ``outlen'' is larger than the default size it is set to the default
+size to show how many bytes were actually used.
+Similar to the HMAC code the file and memory functions are also provided.  To OMAC a buffer of memory in one shot use the
+following function.
+\begin{verbatim}
+int omac_memory(int cipher,
+const unsigned char *key, unsigned long keylen,
+const unsigned char *msg, unsigned long msglen,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+This will compute the OMAC of ``msglen'' bytes of ``msg'' using the key ``key'' of length ``keylen'' bytes and the cipher
+specified by the ``cipher'''th entry in the cipher\_descriptor table.  It will store the MAC in ``out'' with the same
+rules as omac\_done.
+To OMAC a file use
+\begin{verbatim}
+int omac_file(int cipher,
+const unsigned char *key, unsigned long keylen,
+const char *filename,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+Which will OMAC the entire contents of the file specified by ``filename'' using the key ``key'' of length ``keylen'' bytes
+and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table.  It will store the MAC in ``out'' with
+the same rules as omac\_done.
+To test if the OMAC code is working there is the following function:
+\begin{verbatim}
+int omac_test(void);
+\end{verbatim}
+Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code.  Some example code for using the
+OMAC system is given below.
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+int idx, err;
+omac_state omac;
+unsigned char key[16], dst[MAXBLOCKSIZE];
+unsigned long dstlen;
+/* register Rijndael */
+if (register_cipher(&rijndael_desc) == -1) {
+printf("Error registering Rijndael\n");
+return -1;
+}
+/* get index of Rijndael in cipher descriptor table */
+idx = find_cipher("rijndael");
+/* we would make up our symmetric key in "key[]" here */
+/* start the OMAC */
+if ((err = omac_init(&omac, idx, key, 16)) != CRYPT_OK) {
+printf("Error setting up omac: %s\n", error_to_string(err));
+return -1;
+}
+/* process a few octets */
+if((err = omac_process(&omac, "hello", 5) != CRYPT_OK) {
+printf("Error processing omac: %s\n", error_to_string(err));
+return -1;
+}
+/* get result (presumably to use it somehow...) */
+dstlen = sizeof(dst);
+if ((err = omac_done(&omac, dst, &dstlen)) != CRYPT_OK) {
+printf("Error finishing omac: %s\n", error_to_string(err));
+return -1;
+}
+printf("The omac is %lu bytes long\n", dstlen);
+/* return */
+return 0;
+}
+\end{verbatim}
+\end{small}
+\section{PMAC Support}
+The PMAC\footnote{J.Black, P.Rogaway, ``A Block--Cipher Mode of Operation for Parallelizable Message Authentication''}
+protocol is another MAC algorithm that relies solely on a symmetric-key block cipher.  It uses essentially the same
+API as the provided OMAC code.
+A PMAC state is initialized with the following.
+\begin{verbatim}
+int pmac_init(pmac_state *pmac, int cipher,
+const unsigned char *key, unsigned long keylen);
+\end{verbatim}
+Which initializes the ``pmac'' state with the given ``cipher'' and ``key'' of length ``keylen'' bytes.  The chosen cipher
+must have a 64 or 128 bit block size (e.x. AES).
+To MAC data simply send it through the process function.
+\begin{verbatim}
+int pmac_process(pmac_state *state,
+const unsigned char *buf, unsigned long len);
+\end{verbatim}
+This will process ``len'' bytes of ``buf'' in the given ``state''.  The function is not sensitive to the granularity of the
+data.  For example,
+\begin{verbatim}
+pmac_process(&mystate, "hello",  5);
+pmac_process(&mystate, " world", 6);
+\end{verbatim}
+Would produce the same result as,
+\begin{verbatim}
+pmac_process(&mystate, "hello world",  11);
+\end{verbatim}
+When a complete message has been processed the following function can be called to compute the message tag.
+\begin{verbatim}
+int pmac_done(pmac_state *state,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+This will store upto ``outlen'' bytes of the tag for the given ``state'' into ``out''.  Note that if ``outlen'' is larger
+than the size of the tag it is set to the amount of bytes stored in ``out''.
+Similar to the PMAC code the file and memory functions are also provided.  To PMAC a buffer of memory in one shot use the
+following function.
+\begin{verbatim}
+int pmac_memory(int cipher,
+const unsigned char *key, unsigned long keylen,
+const unsigned char *msg, unsigned long msglen,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+This will compute the PMAC of ``msglen'' bytes of ``msg'' using the key ``key'' of length ``keylen'' bytes and the cipher
+specified by the ``cipher'''th entry in the cipher\_descriptor table.  It will store the MAC in ``out'' with the same
+rules as omac\_done.
+To PMAC a file use
+\begin{verbatim}
+int pmac_file(int cipher,
+const unsigned char *key, unsigned long keylen,
+const char *filename,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+Which will PMAC the entire contents of the file specified by ``filename'' using the key ``key'' of length ``keylen'' bytes
+and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table.  It will store the MAC in ``out'' with
+the same rules as omac\_done.
+To test if the PMAC code is working there is the following function:
+\begin{verbatim}
+int pmac_test(void);
+\end{verbatim}
+Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code.
+\chapter{Pseudo-Random Number Generators}
+\section{Core Functions}
+The library provides an array of core functions for Pseudo-Random Number Generators (PRNGs) as well.  A cryptographic PRNG is
+used to expand a shorter bit string into a longer bit string.  PRNGs are used wherever random data is required such as Public Key (PK)
+key generation.  There is a universal structure called ``prng\_state''.  To initialize a PRNG call:
+\begin{verbatim}
+int XXX_start(prng_state *prng);
+\end{verbatim}
+This will setup the PRNG for future use and not seed it.  In order
+for the PRNG to be cryptographically useful you must give it entropy.  Ideally you'd have some OS level source to tap
+like in UNIX (see section 5.3).  To add entropy to the PRNG call:
+\begin{verbatim}
+int XXX_add_entropy(const unsigned char *in, unsigned long len,
+prng_state *prng);
+\end{verbatim}
+Which returns {\bf CRYPTO\_OK} if the entropy was accepted.  Once you think you have enough entropy you call another
+function to put the entropy into action.
+\begin{verbatim}
+int XXX_ready(prng_state *prng);
+\end{verbatim}
+Which returns {\bf CRYPTO\_OK} if it is ready.  Finally to actually read bytes call:
+\begin{verbatim}
+unsigned long XXX_read(unsigned char *out, unsigned long len,
+prng_state *prng);
+\end{verbatim}
+Which returns the number of bytes read from the PRNG.
+\subsection{Remarks}
+It is possible to be adding entropy and reading from a PRNG at the same time.  For example, if you first seed the PRNG
+and call ready() you can now read from it.  You can also keep adding new entropy to it.  The new entropy will not be used
+in the PRNG until ready() is called again.  This allows the PRNG to be used and re-seeded at the same time.  No real error
+checking is guaranteed to see if the entropy is sufficient or if the PRNG is even in a ready state before reading.
+\subsection{Example}
+Below is a simple snippet to read 10 bytes from yarrow.  Its important to note that this snippet is {\bf NOT} secure since
+the entropy added is not random.
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+prng_state prng;
+unsigned char buf[10];
+int err;
+/* start it */
+if ((err = yarrow_start(&prng)) != CRYPT_OK) {
+printf("Start error: %s\n", error_to_string(err));
+}
+/* add entropy */
+if ((err = yarrow_add_entropy("hello world", 11, &prng)) != CRYPT_OK) {
+printf("Add_entropy error: %s\n", error_to_string(err));
+}
+/* ready and read */
+if ((err = yarrow_ready(&prng)) != CRYPT_OK) {
+printf("Ready error: %s\n", error_to_string(err));
+}
+printf("Read %lu bytes from yarrow\n", yarrow_read(buf, 10, &prng));
+return 0;
+}
+\end{verbatim}
+\section{PRNG Descriptors}
+\index{PRNG Descriptor}
+PRNGs have descriptors too (surprised?). Stored in the structure ``prng\_descriptor''.  The format of an element is:
+\begin{verbatim}
+struct _prng_descriptor {
+char *name;
+int (*start)      (prng_state *);
+int (*add_entropy)(const unsigned char *, unsigned long, prng_state *);
+int (*ready)      (prng_state *);
+unsigned long (*read)(unsigned char *, unsigned long len, prng_state *);
+};
+\end{verbatim}
+There is a ``int find\_prng(char *name)'' function as well.  Returns -1 if the PRNG is not found, otherwise it returns
+the position in the prng\_descriptor array.
+Just like the ciphers and hashes you must register your prng before you can use it.  The two functions provided work
+exactly as those for the cipher registry functions.  They are:
+\begin{verbatim}
+int register_prng(const struct _prng_descriptor *prng);
+int unregister_prng(const struct _prng_descriptor *prng);
+\end{verbatim}
+\subsubsection{PRNGs Provided}
+Currently Yarrow (yarrow\_desc), RC4 (rc4\_desc) and the secure RNG (sprng\_desc) are provided as PRNGs within the
+library.
+RC4 is provided with a PRNG interface because it is a stream cipher and not well suited for the symmetric block cipher
+interface.  You provide the key for RC4 via the rc4\_add\_entropy() function.  By calling rc4\_ready() the key will be used
+to setup the RC4 state for encryption or decryption.  The rc4\_read() function has been modified from RC4 since it will
+XOR the output of the RC4 keystream generator against the input buffer you provide.  The following snippet will demonstrate
+how to encrypt a buffer with RC4:
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+prng_state prng;
+unsigned char buf[32];
+int err;
+if ((err = rc4_start(&prng)) != CRYPT_OK) {
+printf("RC4 init error: %s\n", error_to_string(err));
+exit(-1);
+}
+/* use ``key'' as the key */
+if ((err = rc4_add_entropy("key", 3, &prng)) != CRYPT_OK) {
+printf("RC4 add entropy error: %s\n", error_to_string(err));
+exit(-1);
+}
+/* setup RC4 for use */
+if ((err = rc4_ready(&prng)) != CRYPT_OK) {
+printf("RC4 ready error: %s\n", error_to_string(err));
+exit(-1);
+}
+/* encrypt buffer */
+strcpy(buf,"hello world");
+if (rc4_read(buf, 11, &prng) != 11) {
+printf("RC4 read error\n");
+exit(-1);
+}
+return 0;
+}
+\end{verbatim}
+\end{small}
+To decrypt you have to do the exact same steps.
+\section{The Secure RNG}
+\index{Secure RNG}
+An RNG is related to a PRNG except that it doesn't expand a smaller seed to get the data.  They generate their random bits
+by performing some computation on fresh input bits.  Possibly the hardest thing to get correctly in a cryptosystem is the
+PRNG.  Computers are deterministic beasts that try hard not to stray from pre-determined paths.  That makes gathering
+entropy needed to seed the PRNG a hard task.
+There is one small function that may help on certain platforms:
+\index{rng\_get\_bytes()}
+\begin{verbatim}
+unsigned long rng_get_bytes(unsigned char *buf, unsigned long len,
+void (*callback)(void));
+\end{verbatim}
+Which will try one of three methods of getting random data.  The first is to open the popular ``/dev/random'' device which
+on most *NIX platforms provides cryptographic random bits\footnote{This device is available in Windows through the Cygwin compiler suite.  It emulates ``/dev/random'' via the Microsoft CSP.}.
+The second method is to try the Microsoft Cryptographic Service Provider and read the RNG.  The third method is an ANSI C
+clock drift method that is also somewhat popular but gives bits of lower entropy.  The ``callback'' parameter is a pointer to a function that returns void.  Its used when the slower ANSI C RNG must be
+used so the calling application can still work.  This is useful since the ANSI C RNG has a throughput of three
+bytes a second.  The callback pointer may be set to {\bf NULL} to avoid using it if you don't want to.  The function
+returns the number of bytes actually read from any RNG source.  There is a function to help setup a PRNG as well:
+\index{rng\_make\_prng()}
+\begin{verbatim}
+int rng_make_prng(int bits, int wprng, prng_state *prng,
+void (*callback)(void));
+\end{verbatim}
+This will try to setup the prng with a state of at least ``bits'' of entropy.  The ``callback'' parameter works much like
+the callback in ``rng\_get\_bytes()''.  It is highly recommended that you use this function to setup your PRNGs unless you have a
+platform where the RNG doesn't work well.  Example usage of this function is given below.
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+ecc_key mykey;
+prng_state prng;
+int err;
+/* register yarrow */
+if (register_prng(&yarrow_desc) == -1) {
+printf("Error registering Yarrow\n");
+return -1;
+}
+/* setup the PRNG */
+if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) != CRYPT_OK) {
+printf("Error setting up PRNG, %s\n", error_to_string(err));
+return -1;
+}
+/* make a 192-bit ECC key */
+if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) != CRYPT_OK) {
+printf("Error making key: %s\n", error_to_string(err));
+return -1;
+}
+return 0;
+}
+\end{verbatim}
+\end{small}
+\subsection{The Secure PRNG Interface}
+It is possible to access the secure RNG through the PRNG interface and in turn use it within dependent functions such
+as the PK API.  This simplifies the cryptosystem on platforms where the secure RNG is fast.  The secure PRNG never
+requires to be started, that is you need not call the start, add\_entropy or ready functions.  For example, consider
+the previous example using this PRNG.
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+ecc_key mykey;
+int err;
+/* register SPRNG */
+if (register_prng(&sprng_desc) == -1) {
+printf("Error registering SPRNG\n");
+return -1;
+}
+/* make a 192-bit ECC key */
+if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) != CRYPT_OK) {
+printf("Error making key: %s\n", error_to_string(err));
+return -1;
+}
+return 0;
+}
+\end{verbatim}
+\end{small}
+\chapter{RSA Public Key Cryptography}
+\textbf{Note: } \textit{This chapter on PKCS \#1 RSA will replace the older chapter on RSA (The current chapter nine) in subsequent
+releases of the library.  Users are encouraged to stop using the LibTomCrypt style padding functions.}
+\section{PKCS \#1 Encryption}
+PKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation.  As far as this portion of
+the library is concerned we are only dealing with th OAEP padding of the message.
+\subsection{OAEP Encoding}
+\begin{alltt}
+int pkcs_1_oaep_encode(const unsigned char *msg,    unsigned long msglen,
+const unsigned char *lparam, unsigned long lparamlen,
+unsigned long modulus_bitlen, int hash_idx,
+int           prng_idx,    prng_state *prng,
+unsigned char *out,    unsigned long *outlen);
+\end{alltt}
+This accepts ``msg'' as input of length ``msglen'' which will be OAEP padded.  The ``lparam'' variable is an additional system specific
+tag that can be applied to the encoding.  This is useful to identify which system encoded the message.  If no variance is desired then
+``lparam'' can be set to \textbf{NULL}.
+OAEP encoding requires the length of the modulus in bits in order to calculate the size of the output.  This is passed as the parameter
+``modulus\_bitlen''.  ``hash\_idx'' is the index into the hash descriptor table of the hash desired.  PKCS \#1 allows any hash to be
+used but both the encoder and decoder must use the same hash in order for this to succeed.  The size of hash output affects the maximum
+sized input message.  ``prng\_idx'' and ``prng'' are the random number generator arguments required to randomize the padding process.
+The padded message is stored in ``out'' along with the length in ``outlen''.
+If $h$ is the length of the hash and $m$ the length of the modulus (both in octets) then the maximum payload for ``msg'' is
+$m - 2h - 2$.  For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes.
+Note that when the message is padded it still has not been RSA encrypted.  You must pass the output of this function to
+rsa\_exptmod() to encrypt it.
+\subsection{OAEP Decoding}
+\begin{alltt}
+int pkcs_1_oaep_decode(const unsigned char *msg,    unsigned long msglen,
+const unsigned char *lparam, unsigned long lparamlen,
+unsigned long modulus_bitlen, int hash_idx,
+unsigned char *out,    unsigned long *outlen);
+\end{alltt}
+This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder.  ``msg'' is the
+output of pkcs\_1\_oaep\_encode() of length ``msglen''.  ``lparam'' is the same system variable passed to the OAEP encoder.  If it does not
+match what was used during encoding this function will not decode the packet.  ``modulus\_bitlen'' is the size of the RSA modulus in bits
+and must match what was used during encoding.  Similarly the ``hash\_idx'' index into the hash descriptor table must match what was used
+during encoding.
+If the function succeeds it decodes the OAEP encoded message into ``out'' of length ``outlen''.
+\section{PKCS \#1 Digital Signatures}
+\subsection{PSS Encoding}
+PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed.
+\begin{alltt}
+int pkcs_1_pss_encode(const unsigned char *msghash, unsigned long msghashlen,
+unsigned long saltlen,  int           hash_idx,
+int           prng_idx, prng_state   *prng,
+unsigned long modulus_bitlen,
+unsigned char *out,     unsigned long *outlen);
+\end{alltt}
+This function assumes the message to be PSS encoded has previously been hashed.  The input hash ``msghash'' is of length
+``msghashlen''.  PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process.
+``hash\_idx'' is the index into the hash descriptor table of the hash to use.  ``prng\_idx'' and ``prng'' are the random
+number generator information required for the salt.
+Similar to OAEP encoding ``modulus\_bitlen'' is the size of the RSA modulus.  It limits the size of the salt.  If $m$ is the length
+of the modulus $h$ the length of the hash output (in octets) then there can be $m - h - 2$ bytes of salt.
+This function does not actually sign the data it merely pads the hash of a message so that it can be processed by rsa\_exptmod().
+\subsection{PSS Decoding}
+To decode a PSS encoded signature block you have to use the following.
+\begin{alltt}
+int pkcs_1_pss_decode(const unsigned char *msghash, unsigned long msghashlen,
+const unsigned char *sig,     unsigned long siglen,
+unsigned long saltlen,  int           hash_idx,
+unsigned long modulus_bitlen, int    *res);
+\end{alltt}
+This will decode the PSS encoded message in ``sig'' of length ``siglen'' and compare it to values in ``msghash'' of length
+``msghashlen''.  If the block is a valid PSS block and the decoded hash equals the hash supplied ``res'' is set to non--zero.  Otherwise,
+it is set to zero.  The rest of the parameters are as in the PSS encode call.
+It's important to use the same ``saltlen'' and hash for both encoding and decoding as otherwise the procedure will not work.
+\chapter{Password Based Cryptography}
+\section{PKCS \#5}
+In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted.   PKCS \#5
+is made up of two algorithms, Algorithm One and Algorithm Two.  Algorithm One is the older fairly limited algorithm which has been implemented
+for completeness.  Algorithm Two is a bit more modern and more flexible to work with.
+\section{Algorithm One}
+Algorithm One accepts as input a password, an 8--byte salt and an iteration counter.  The iteration counter is meant to act as delay for
+people trying to brute force guess the password.  The higher the iteration counter the longer the delay.  This algorithm also requires a hash
+algorithm and produces an output no longer than the output of the hash.
+\begin{alltt}
+int pkcs_5_alg1(const unsigned char *password, unsigned long password_len,
+const unsigned char *salt,
+int iteration_count,  int hash_idx,
+unsigned char *out,   unsigned long *outlen)
+\end{alltt}
+Where ``password'' is the users password.  Since the algorithm allows binary passwords you must also specify the length in ``password\_len''.
+The ``salt'' is a fixed size 8--byte array which should be random for each user and session.  The ``iteration\_count'' is the delay desired
+on the password.  The ``hash\_idx'' is the index of the hash you wish to use in the descriptor table.
+The output of length upto ``outlen'' is stored in ``out''.  If ``outlen'' is initially larger than the size of the hash functions output
+it is set to the number of bytes stored.  If it is smaller than not all of the hash output is stored in ``out''.
+\section{Algorithm Two}
+Algorithm Two is the recommended algorithm for this task.  It allows variable length salts and can produce outputs larger than the
+hash functions output.  As such it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required
+from a single password and invokation of this algorithm.
+\begin{alltt}
+int pkcs_5_alg2(const unsigned char *password, unsigned long password_len,
+const unsigned char *salt,     unsigned long salt_len,
+int iteration_count,           int hash_idx,
+unsigned char *out,            unsigned long *outlen)
+\end{alltt}
+Where ``password'' is the users password.  Since the algorithm allows binary passwords you must also specify the length in ``password\_len''.
+The ``salt'' is an array of size ``salt\_len''.  It should be random for each user and session.  The ``iteration\_count'' is the delay desired
+on the password.  The ``hash\_idx'' is the index of the hash you wish to use in the descriptor table.   The output of length upto
+``outlen'' is stored in ``out''.
+\begin{alltt}
+/* demo to show how to make session state material from a password */
+#include <mycrypt.h>
+int main(void)
+\{
+unsigned char password[100], salt[100],
+cipher_key[16], cipher_iv[16],
+mac_key[16], outbuf[48];
+int           err, hash_idx;
+unsigned long outlen, password_len, salt_len;
+/* register hash and get it's idx .... */
+/* get users password and make up a salt ... */
+/* create the material (100 iterations in algorithm) */
+outlen = sizeof(outbuf);
+if ((err = pkcs_5_alg2(password, password_len, salt, salt_len,
+100, hash_idx, outbuf, &outlen)) != CRYPT_OK) \{
+/* error handle */
+\}
+/* now extract it */
+memcpy(cipher_key, outbuf, 16);
+memcpy(cipher_iv,  outbuf+16, 16);
+memcpy(mac_key,    outbuf+32, 16);
+/* use material (recall to store the salt in the output) */
+\}
+\end{alltt}
+\chapter{RSA Routines}
+\textbf{Note: } \textit{This chapter has been marked for removal.  In particular any function that uses the LibTomCrypt style
+RSA padding (e.g. rsa\_pad() rsa\_signpad())  will be removed in the v0.96 release cycle.  The functions like rsa\_make\_key() and
+rsa\_exptmod() will stay but may be slightly modified. }
+\section{Background}
+RSA is a public key algorithm that is based on the inability to find the ``e-th'' root modulo a composite of unknown
+factorization.  Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are
+not strictly equivalent.
+The system begins with with two primes $p$ and $q$ and their product $N = pq$.  The order or ``Euler totient'' of the
+multiplicative sub-group formed modulo $N$ is given as $\phi(N) = (p - 1)(q - 1)$ which can be reduced to
+$\mbox{lcm}(p - 1, q - 1)$.  The public key consists of the composite $N$ and some integer $e$ such that
+$\mbox{gcd}(e, \phi(N)) = 1$.  The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$
+often simply denoted as $de \equiv 1\mbox{ }(\mbox{mod }\phi(N))$.
+A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that
+$1 < M < N-2$ and computes the ciphertext $C = M^e\mbox{ }(\mbox{mod }N)$.  Since finding the inverse exponent $d$
+given only $N$ and $e$ appears to be intractable only the owner of the private key can decrypt the ciphertext and compute
+$C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$.  Similarly the owner of the private key
+can sign a message by ``decrypting'' it.  Others can verify it by ``encrypting'' it.
+Currently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other.
+Ideally $e$ should be larger than $100$ to prevent direct analysis.  For example, if $e$ is three and you do not pad
+the plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial.
+The most often suggested value for $e$ is $65537$ since it is large enough to make such attacks impossible and also well
+designed for fast exponentiation (requires 16 squarings and one multiplication).
+It is important to pad the input to RSA since it has particular mathematical structure.  For instance
+$M_1^dM_2^d = (M_1M_2)^d$ which can be used to forge a signature.  Suppose $M_3 = M_1M_2$ is a message you want
+to have a forged signature for.  Simply get the signatures for $M_1$ and $M_2$ on their own and multiply the result
+together.  Similar tricks can be used to deduce plaintexts from ciphertexts.  It is important not only to sign
+the hash of documents only but also to pad the inputs with data to remove such structure.
+\section{Core Functions}
+For RSA routines a single ``rsa\_key'' structure is used.  To make a new RSA key call:
+\index{rsa\_make\_key()}
+\begin{verbatim}
+int rsa_make_key(prng_state *prng,
+int wprng, int size,
+long e, rsa_key *key);
+\end{verbatim}
+Where ``wprng'' is the index into the PRNG descriptor array.  ``size'' is the size in bytes of the RSA modulus desired.
+``e'' is the encryption exponent desired, typical values are 3, 17, 257 and 65537.  I suggest you stick with 65537 since its big
+enough to prevent trivial math attacks and not super slow.  ``key'' is where the key is placed.  All keys must be at
+least 128 bytes and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}).
+Note that the ``rsa\_make\_key()'' function allocates memory at runtime when you make the key.  Make sure to call
+``rsa\_free()'' (see below) when you are finished with the key.  If ``rsa\_make\_key()'' fails it will automatically
+free the ram allocated itself.
+There are three types of RSA keys.  The types are {\bf PK\_PRIVATE\_OPTIMIZED}, {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}.  The first
+two are private keys where the ``optimized'' type uses the Chinese Remainder Theorem to speed up decryption/signatures.  By
+default all new keys are of the ``optimized'' type.  The non-optimized private type is provided for backwards compatibility
+as well as to save space since the optimized key requires about four times as much memory.
+To do raw work with the RSA function call:
+\index{rsa\_exptmod()}
+\begin{verbatim}
+int rsa_exptmod(const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen,
+int which, rsa_key *key);
+\end{verbatim}
+This loads the bignum from ``in'' as a big endian word in the format PKCS specifies, raises it to either ``e'' or ``d'' and stores the result
+in ``out'' and the size of the result in ``outlen''. ``which'' is set to {\bf PK\_PUBLIC} to use ``e''
+(i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use ``d'' as the exponent (i.e. for decrypting/signing).
+Note that this function does not perform padding on the input (as per PKCS).  So if you send in ``0000001'' you will
+get ``01'' back (when you do the opposite operation).  Make sure you pad properly which usually involves setting the msb to
+a non-zero value.
+\section{Packet Routines}
+To encrypt or decrypt a symmetric key using RSA the following functions are provided.  The idea is that you make up
+a random symmetric key and use that to encode your message.  By RSA encrypting the symmetric key you can send it to a
+recipient who can RSA decrypt it and symmetrically decrypt the message.
+\begin{verbatim}
+int rsa_encrypt_key(const unsigned char *inkey, unsigned long inlen,
+unsigned char *outkey, unsigned long *outlen,
+prng_state *prng, int wprng, rsa_key *key);
+\end{verbatim}
+This function is used to RSA encrypt a symmetric to share with another user.  The symmetric key and its length are
+passed as ``inkey'' and ``inlen'' respectively.  The symmetric key is limited to a range of 8 to 32 bytes
+(\textit{64 to 256 bits}).  The RSA encrypted packet is stored in ``outkey'' and will be of length ``outlen'' bytes.  The
+value of ``outlen'' must be originally set to the size of the output buffer.
+\begin{verbatim}
+int rsa_decrypt_key(const unsigned char *in, unsigned long inlen,
+unsigned char *outkey, unsigned long *keylen,
+rsa_key *key);
+\end{verbatim}
+This function will decrypt an RSA packet to retrieve the original symmetric key encrypted with rsa\_encrypt\_key().
+Similarly to sign or verify a hash of a message the following two messages are provided.  The idea is to hash your message
+then use these functions to RSA sign the hash.
+\begin{verbatim}
+int rsa_sign_hash(const unsigned char *in,  unsigned long inlen,
+unsigned char *out, unsigned long *outlen,
+rsa_key *key);
+int rsa_verify_hash(const unsigned char *sig, unsigned long siglen,
+const unsigned char *hash, int *stat, rsa_key *key);
+\end{verbatim}
+For ``rsa\_sign\_hash'' the input is intended to be the hash of a message the user wants to sign.  The output is the
+RSA signed packet which ``rsa\_verify\_hash'' can verify.  For the verification function ``sig'' is the RSA signature
+and ``hash'' is the hash of the message.  The integer ``stat'' is set to non-zero if the signature is valid or zero
+otherwise.
+To import/export RSA keys as a memory buffer (e.g. to store them to disk) call:
+\begin{verbatim}
+int rsa_export(unsigned char *out, unsigned long *outlen,
+int type, rsa_key *key);
+int rsa_import(const unsigned char *in, unsigned long inlen, rsa_key *key);
+\end{verbatim}
+The ``type'' parameter is {\bf PK\_PUBLIC}, {\bf PK\_PRIVATE} or {\bf PK\_PRIVATE\_OPTIMIZED} to export either a public or
+private key.  The latter type will export a key with the optimized parameters.  To free the memory used by an RSA key call:
+\index{rsa\_free()}
+\begin{verbatim}
+void rsa_free(rsa_key *key);
+\end{verbatim}
+Note that if the key fails to ``rsa\_import()'' you do not have to free the memory allocated for it.
+\section{Remarks}
+It is important that you match your RSA key size with the function you are performing.  The internal padding for both
+signatures and encryption triple the size of the plaintext.  This means to encrypt or sign
+a message of N bytes you must have a modulus of 1+3N bytes.  Note that this doesn't affect the length of the plaintext
+you pass into functions like rsa\_encrypt().  This restriction applies only to data that is passed through the
+internal RSA routines directly directly.
+The following table gives the size requirements for various hashes.
+\begin{center}
+\begin{tabular}{|c|c|c|}
+\hline Name & Size of Message Digest (bytes) & RSA Key Size (bits)\\
+\hline SHA-512 & 64 & 1544\\
+\hline SHA-384 & 48 & 1160 \\
+\hline SHA-256 & 32 & 776\\
+\hline TIGER-192 & 24 & 584\\
+\hline SHA-1 & 20 & 488\\
+\hline MD5 & 16 & 392\\
+\hline MD4 & 16 & 392\\
+\hline
+\end{tabular}
+\end{center}
+The symmetric ciphers will use at a maximum a 256-bit key which means at the least a 776-bit RSA key is
+required to use all of the symmetric ciphers with the RSA routines. If you want to use any of the large size
+message digests (SHA-512 or SHA-384) you will have to use a larger key.  Or to be simple just make 2048-bit or larger
+keys.  None of the hashes will have problems with such key sizes.
+\chapter{Diffie-Hellman Key Exchange}
+\section{Background}
+Diffie-Hellman was the original public key system proposed.  The system is based upon the group structure
+of finite fields.  For Diffie-Hellman a prime $p$ is chosen and a ``base'' $b$ such that $b^x\mbox{ }(\mbox{mod }p)$
+generates a large sub-group of prime order (for unique values of $x$).
+A secret key is an exponent $x$ and a public key is the value of $y \equiv g^x\mbox{ }(\mbox{mod }p)$.  The term
+``discrete logarithm'' denotes the action of finding $x$ given only $y$, $g$ and $p$.  The key exchange part of
+Diffie-Hellman arises from the fact that two users A and B with keys $(A_x, A_y)$ and $(B_x, B_y)$ can exchange
+a shared key $K \equiv B_y^{A_x} \equiv A_y^{B_x} \equiv g^{A_xB_x}\mbox{ }(\mbox{mod }p)$.
+From this public encryption and signatures can be developed.  The trivial way to encrypt (for example) using a public key
+$y$ is to perform the key exchange offline.  The sender invents a key $k$ and its public copy
+$k' \equiv g^k\mbox{ }(\mbox{mod }p)$ and uses $K \equiv k'^{A_x}\mbox{ }(\mbox{mod }p)$ as a key to encrypt
+the message with.  Typically $K$ would be sent to a one-way hash and the message digested used as a key in a
+symmetric cipher.
+It is important that the order of the sub-group that $g$ generates not only be large but also prime.  There are
+discrete logarithm algorithms that take $\sqrt r$ time given the order $r$.  The discrete logarithm can be computed
+modulo each prime factor of $r$ and the results combined using the Chinese Remainder Theorem.  In the cases where
+$r$ is ``B-Smooth'' (e.g. all small factors or powers of small prime factors) the solution is trivial to find.
+To thwart such attacks the primes and bases in the library have been designed and fixed.  Given a prime $p$ the order of
+the sub-group generated is a large prime namely ${p - 1} \over 2$.  Such primes are known as ``strong primes'' and the
+smaller prime (e.g. the order of the base) are known as Sophie-Germaine primes.
+\section{Core Functions}
+This library also provides core Diffie-Hellman functions so you can negotiate keys over insecure mediums.  The routines
+provided are relatively easy to use and only take two function calls to negotiate a shared key.  There is a structure
+called ``dh\_key'' which stores the Diffie-Hellman key in a format these routines can use.  The first routine is to
+make a Diffie-Hellman private key pair:
+\index{dh\_make\_key()}
+\begin{verbatim}
+int dh_make_key(prng_state *prng, int wprng,
+int keysize, dh_key *key);
+\end{verbatim}
+The ``keysize'' is the size of the modulus you want in bytes.  Currently support sizes are 96 to 512 bytes which correspond
+to key sizes of 768 to 4096 bits. The smaller the key the faster it is to use however it will be less secure.  When
+specifying a size not explicitly supported by the library it will round {\em up} to the next key size.  If the size is
+above 512 it will return an error.  So if you pass ``keysize == 32'' it will use a 768 bit key but if you pass
+``keysize == 20000'' it will return an error.  The primes and generators used are built-into the library and were designed
+to meet very specific goals.  The primes are strong primes which means that if $p$ is the prime then
+$p-1$ is equal to $2r$ where $r$ is a large prime.  The bases are chosen to generate a group of order $r$ to prevent
+leaking a bit of the key.  This means the bases generate a very large prime order group which is good to make cryptanalysis
+hard.
+The next two routines are for exporting/importing Diffie-Hellman keys in a binary format.  This is useful for transport
+over communication mediums.
+\index{dh\_export()} \index{dh\_import()}
+\begin{verbatim}
+int dh_export(unsigned char *out, unsigned long *outlen,
+int type, dh_key *key);
+int dh_import(const unsigned char *in, unsigned long inlen, dh_key *key);
+\end{verbatim}
+These two functions work just like the ``rsa\_export()'' and ``rsa\_import()'' functions except these work with
+Diffie-Hellman keys. Its important to note you do not have to free the ram for a ``dh\_key'' if an import fails.  You can free a
+``dh\_key'' using:
+\begin{verbatim}
+void dh_free(dh_key *key);
+\end{verbatim}
+After you have exported a copy of your public key (using {\bf PK\_PUBLIC} as ``type'') you can now create a shared secret
+with the other user using:
+\index{dh\_shared\_secret()}
+\begin{verbatim}
+int dh_shared_secret(dh_key *private_key,
+dh_key *public_key,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+Where ``private\_key'' is the key you made and ``public\_key'' is the copy of the public key the other user sent you.  The result goes
+into ``out'' and the length into ``outlen''.  If all went correctly the data in ``out'' should be identical for both parties.  It is important to
+note that the two keys have to be the same size in order for this to work.  There is a function to get the size of a
+key:
+\index{dh\_get\_size()}
+\begin{verbatim}
+int dh_get_size(dh_key *key);
+\end{verbatim}
+This returns the size in bytes of the modulus chosen for that key.
+\subsection{Remarks on Usage}
+Its important that you hash the shared key before trying to use it as a key for a symmetric cipher or something.  An
+example program that communicates over sockets, using MD5 and 1024-bit DH keys is\footnote{This function is a small example.  It is suggested that proper packaging be used.  For example, if the public key sent is truncated these routines will not detect that.}:
+\newpage
+\begin{small}
+\begin{verbatim}
+int establish_secure_socket(int sock, int mode, unsigned char *key,
+prng_state *prng, int wprng)
+{
+unsigned char buf[4096], buf2[4096];
+unsigned long x, len;
+int res, err, inlen;
+dh_key mykey, theirkey;
+/* make up our private key */
+if ((err = dh_make_key(prng, wprng, 128, &mykey)) != CRYPT_OK)  {
+return err;
+}
+/* export our key as public */
+x = sizeof(buf);
+if ((err = dh_export(buf, &x, PK_PUBLIC, &mykey)) != CRYPT_OK) {
+res = err;
+goto done2;
+}
+if (mode == 0) {
+/* mode 0 so we send first */
+if (send(sock, buf, x, 0) != x) {
+res = CRYPT_ERROR;
+goto done2;
+}
+/* get their key */
+if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) {
+res = CRYPT_ERROR;
+goto done2;
+}
+} else {
+/* mode >0 so we send second */
+if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) {
+res = CRYPT_ERROR;
+goto done2;
+}
+if (send(sock, buf, x, 0) != x) {
+res = CRYPT_ERROR;
+goto done2;
+}
+}
+if ((err = dh_import(buf2, inlen, &theirkey)) != CRYPT_OK) {
+res = err;
+goto done2;
+}
+/* make shared secret */
+x = sizeof(buf);
+if ((err = dh_shared_secret(&mykey, &theirkey, buf, &x)) != CRYPT_OK) {
+res = err;
+goto done;
+}
+/* hash it */
+len = 16;        /* default is MD5 so "key" must be at least 16 bytes long */
+if ((err = hash_memory(find_hash("md5"), buf, x, key, &len)) != CRYPT_OK) {
+res = err;
+goto done;
+}
+/* clean up and return */
+res = CRYPT_OK;
+done:
+dh_free(&theirkey);
+done2:
+dh_free(&mykey);
+zeromem(buf,  sizeof(buf));
+zeromem(buf2, sizeof(buf2));
+return res;
+}
+\end{verbatim}
+\end{small}
+\newpage
+\subsection{Remarks on The Snippet}
+When the above code snippet is done (assuming all went well) their will be a shared 128-bit key in the ``key'' array
+passed to ``establish\_secure\_socket()''.
+\section{Other Diffie-Hellman Functions}
+In order to test the Diffie-Hellman function internal workings (e.g. the primes and bases) their is a test function made
+available:
+\index{dh\_test()}
+\begin{verbatim}
+int dh_test(void);
+\end{verbatim}
+This function returns {\bf CRYPT\_OK} if the bases and primes in the library are correct.  There is one last helper
+function:
+\index{dh\_sizes()}
+\begin{verbatim}
+void dh_sizes(int *low, int *high);
+\end{verbatim}
+Which stores the smallest and largest key sizes support into the two variables.
+\section{DH Packet}
+Similar to the RSA related functions there are functions to encrypt or decrypt symmetric keys using the DH public key
+algorithms.
+\begin{verbatim}
+int dh_encrypt_key(const unsigned char *inkey, unsigned long keylen,
+unsigned char *out,  unsigned long *len,
+prng_state *prng, int wprng, int hash,
+dh_key *key);
+int dh_decrypt_key(const unsigned char *in, unsigned long inlen,
+unsigned char *outkey, unsigned long *keylen,
+dh_key *key);
+\end{verbatim}
+Where ``inkey'' is an input symmetric key of no more than 32 bytes.  Essentially these routines created a random public key
+and find the hash of the shared secret.  The message digest is than XOR'ed against the symmetric key.  All of the
+required data is placed in ``out'' by ``dh\_encrypt\_key()''.   The hash must produce a message digest at least as large
+as the symmetric key you are trying to share.
+Similar to the RSA system you can sign and verify a hash of a message.
+\begin{verbatim}
+int dh_sign_hash(const unsigned char *in,  unsigned long inlen,
+unsigned char *out, unsigned long *outlen,
+prng_state *prng, int wprng, dh_key *key);
+int dh_verify_hash(const unsigned char *sig, unsigned long siglen,
+const unsigned char *hash, unsigned long hashlen,
+int *stat, dh_key *key);
+\end{verbatim}
+The ``dh\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a DH packet in ``out''.
+The ``dh\_verify\_hash'' function verifies the DH signature in ``sig'' against the hash in ``hash''.  It sets ``stat''
+to non-zero if the signature passes or zero if it fails.
+\chapter{Elliptic Curve Cryptography}
+\section{Background}
+The library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the
+Diffie-Hellman routines in the previous chapter.  Elliptic curves (of certain forms) have the benefit that they are harder
+to attack (no sub-exponential attacks exist unlike normal DH crypto) in fact the fastest attack requires the square root
+of the order of the base point in time.  That means if you use a base point of order $2^{192}$ (which would represent a
+192-bit key) then the work factor is $2^{96}$ in order to find the secret key.
+The curves in this library are taken from the following website:
+\begin{verbatim}
+http://csrc.nist.gov/cryptval/dss.htm
+\end{verbatim}
+They are all curves over the integers modulo a prime.  The curves have the basic equation that is:
+\begin{equation}
+y^2 = x^3 - 3x + b\mbox{ }(\mbox{mod }p)
+\end{equation}
+The variable $b$ is chosen such that the number of points is nearly maximal.  In fact the order of the base points $\beta$
+provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$.  The curves
+range in order from $\approx 2^{192}$ points to $\approx 2^{521}$.  According to the source document any key size greater
+than or equal to 256-bits is sufficient for long term security.
+\section{Core Functions}
+Like the DH routines there is a key structure ``ecc\_key'' used by the functions.  There is a function to make a key:
+\index{ecc\_make\_key()}
+\begin{verbatim}
+int ecc_make_key(prng_state *prng, int wprng,
+int keysize, ecc_key *key);
+\end{verbatim}
+The ``keysize'' is the size of the modulus in bytes desired.  Currently directly supported values are 20, 24, 28, 32, 48 and 65 bytes which
+correspond to key sizes of 160, 192, 224, 256, 384 and 521 bits respectively.  If you pass a key size that is between any key size
+it will round the keysize up to the next available one.  The rest of the parameters work like they do in the ``dh\_make\_key()'' function.
+To free the ram allocated by a key call:
+\index{ecc\_free()}
+\begin{verbatim}
+void ecc_free(ecc_key *key);
+\end{verbatim}
+To import and export a key there are:
+\index{ecc\_export()}
+\index{ecc\_import()}
+\begin{verbatim}
+int ecc_export(unsigned char *out, unsigned long *outlen,
+int type, ecc_key *key);
+int ecc_import(const unsigned char *in, unsigned long inlen, ecc_key *key);
+\end{verbatim}
+These two work exactly like there DH counterparts.  Finally when you share your public key you can make a shared secret
+with:
+\index{ecc\_shared\_secret()}
+\begin{verbatim}
+int ecc_shared_secret(ecc_key *private_key,
+ecc_key *public_key,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+Which works exactly like the DH counterpart, the ``private\_key'' is your own key and ``public\_key'' is the key the other
+user sent you.   Note that this function stores both $x$ and $y$ co-ordinates of the shared
+elliptic point.  You should hash the output to get a shared key in a more compact and useful form (most of the entropy is
+in $x$ anyways).  Both keys have to be the same size for this to work, to help there is a function to get the size in bytes
+of a key.
+\index{ecc\_get\_size()}
+\begin{verbatim}
+int ecc_get_size(ecc_key *key);
+\end{verbatim}
+To test the ECC routines and to get the minimum and maximum key sizes there are these two functions:
+\index{ecc\_test()}
+\begin{verbatim}
+int ecc_test(void);
+void ecc_sizes(int *low, int *high);
+\end{verbatim}
+Which both work like their DH counterparts.
+\section{ECC Packet}
+Similar to the RSA API there are two functions which encrypt and decrypt symmetric keys using the ECC public key
+algorithms.
+\begin{verbatim}
+int ecc_encrypt_key(const unsigned char *inkey, unsigned long keylen,
+unsigned char *out,  unsigned long *len,
+prng_state *prng, int wprng, int hash,
+ecc_key *key);
+int ecc_decrypt_key(const unsigned char *in, unsigned long inlen,
+unsigned char *outkey, unsigned long *keylen,
+ecc_key *key);
+\end{verbatim}
+Where ``inkey'' is an input symmetric key of no more than 32 bytes.  Essentially these routines created a random public key
+and find the hash of the shared secret.  The message digest is than XOR'ed against the symmetric key.  All of the required
+data is placed in ``out'' by ``ecc\_encrypt\_key()''.   The hash chosen must produce a message digest at least as large
+as the symmetric key you are trying to share.
+There are also functions to sign and verify the hash of a message.
+\begin{verbatim}
+int ecc_sign_hash(const unsigned char *in,  unsigned long inlen,
+unsigned char *out, unsigned long *outlen,
+prng_state *prng, int wprng, ecc_key *key);
+int ecc_verify_hash(const unsigned char *sig, unsigned long siglen,
+const unsigned char *hash, unsigned long hashlen,
+int *stat, ecc_key *key);
+\end{verbatim}
+The ``ecc\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a ECC packet in ``out''.
+The ``ecc\_verify\_hash'' function verifies the ECC signature in ``sig'' against the hash in ``hash''.  It sets ``stat''
+to non-zero if the signature passes or zero if it fails.
+\section{ECC Keysizes}
+With ECC if you try and sign a hash that is bigger than your ECC key you can run into problems.  The math will still work
+and in effect the signature will still work.  With ECC keys the strength of the signature is limited by the size of
+the hash or the size of they key, whichever is smaller.  For example, if you sign with SHA256 and a ECC-160 key in effect
+you have 160-bits of security (e.g. as if you signed with SHA-1).
+The library will not warn you if you make this mistake so it is important to check yourself before using the
+signatures.
+\chapter{Digital Signature Algorithm}
+\section{Introduction}
+The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to
+reduce the bandwidth of a signature.  For example, to have ``80-bits of security'' with ElGamal you need a group of
+order at least 1024-bits.  With DSA you need a group of order at least 160-bits.  By comparison the ElGamal signature
+would require at least 256 bytes where as the DSA signature would require only at least 40 bytes.
+The API for the DSA is essentially the same as the other PK algorithms.  Except in the case of DSA no encryption or
+decryption routines are provided.
+\section{Key Generation}
+To make a DSA key you must call the following function
+\begin{verbatim}
+int dsa_make_key(prng_state *prng, int wprng,
+int group_size, int modulus_size,
+dsa_key *key);
+\end{verbatim}
+The variable ``prng'' is an active PRNG state and ``wprng'' the index to the descriptor.  ``group\_size'' and
+``modulus\_size'' control the difficulty of forging a signature.  Both parameters are in bytes.  The larger the
+``group\_size'' the more difficult a forgery becomes upto a limit.  The value of $group\_size$ is limited by
+$15 < group\_size < 1024$ and $modulus\_size - group\_size < 512$.  Suggested values for the pairs are as follows.
+\begin{center}
+\begin{tabular}{|c|c|c|}
+\hline \textbf{Bits of Security} & \textbf{group\_size} & \textbf{modulus\_size} \\
+\hline 80  & 20 & 128 \\
+\hline 120 & 30 & 256 \\
+\hline 140 & 35 & 384 \\
+\hline 160 & 40 & 512 \\
+\hline
+\end{tabular}
+\end{center}
+When you are finished with a DSA key you can call the following function to free the memory used.
+\begin{verbatim}
+void dsa_free(dsa_key *key);
+\end{verbatim}
+\section{Key Verification}
+Each DSA key is composed of the following variables.
+\begin{enumerate}
+\item $q$ a small prime of magnitude $256^{group\_size}$.
+\item $p = qr + 1$ a large prime of magnitude $256^{modulus\_size}$ where $r$ is a random even integer.
+\item $g = h^r \mbox{ (mod }p\mbox{)}$ a generator of order $q$ modulo $p$.  $h$ can be any non-trivial random
+value.  For this library they start at $h = 2$ and step until $g$ is not $1$.
+\item $x$ a random secret (the secret key) in the range $1 < x < q$
+\item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key.
+\end{enumerate}
+A DSA key is considered valid if it passes all of the following tests.
+\begin{enumerate}
+\item $q$ must be prime.
+\item $p$ must be prime.
+\item $g$ cannot be one of $\lbrace -1, 0, 1 \rbrace$ (modulo $p$).
+\item $g$ must be less than $p$.
+\item $(p-1) \equiv 0 \mbox{ (mod }q\mbox{)}$.
+\item $g^q \equiv 1 \mbox{ (mod }p\mbox{)}$.
+\item $1 < y < p - 1$
+\item $y^q \equiv 1 \mbox{ (mod }p\mbox{)}$.
+\end{enumerate}
+Tests one and two ensure that the values will at least form a field which is required for the signatures to
+function.  Tests three and four ensure that the generator $g$ is not set to a trivial value which would make signature
+forgery easier.  Test five ensures that $q$ divides the order of multiplicative sub-group of $\Z/p\Z$. Test six
+ensures that the generator actually generates a prime order group.  Tests seven and eight ensure that the public key
+is within range and belongs to a group of prime order.  Note that test eight does not prove that $g$ generated $y$ only
+that $y$ belongs to a multiplicative sub-group of order $q$.
+The following function will perform these tests.
+\begin{verbatim}
+int dsa_verify_key(dsa_key *key, int *stat);
+\end{verbatim}
+This will test ``key'' and store the result in ``stat''.  If the result is $stat = 0$ the DSA key failed one of the tests
+and should not be used at all.  If the result is $stat = 1$ the DSA key is valid (as far as valid mathematics are concerned).
+\section{Signatures}
+To generate a DSA signature call the following function
+\begin{verbatim}
+int dsa_sign_hash(const unsigned char *in,  unsigned long inlen,
+unsigned char *out, unsigned long *outlen,
+prng_state *prng, int wprng, dsa_key *key);
+\end{verbatim}
+Which will sign the data in ``in'' of length ``inlen'' bytes.  The signature is stored in ``out'' and the size
+of the signature in ``outlen''.  If the signature is longer than the size you initially specify in ``outlen'' nothing
+is stored and the function returns an error code.  The DSA ``key'' must be of the \textbf{PK\_PRIVATE} persuasion.
+To verify a hash created with that function use the following function
+\begin{verbatim}
+int dsa_verify_hash(const unsigned char *sig, unsigned long siglen,
+const unsigned char *hash, unsigned long inlen,
+int *stat, dsa_key *key);
+\end{verbatim}
+Which will verify the data in ``hash'' of length ``inlen'' against the signature stored in ``sig'' of length ``siglen''.
+It will set ``stat'' to $1$ if the signature is valid, otherwise it sets ``stat'' to $0$.
+\section{Import and Export}
+To export a DSA key so that it can be transported use the following function
+\begin{verbatim}
+int dsa_export(unsigned char *out, unsigned long *outlen,
+int type,
+dsa_key *key);
+\end{verbatim}
+This will export the DSA ``key'' to the buffer ``out'' and set the length in ``outlen'' (which must have been previously
+initialized to the maximum buffer size).  The ``type`` variable may be either \textbf{PK\_PRIVATE} or \textbf{PK\_PUBLIC}
+depending on whether you want to export a private or public copy of the DSA key.
+To import an exported DSA key use the following function
+\begin{verbatim}
+int dsa_import(const unsigned char *in, unsigned long inlen,
+dsa_key *key);
+\end{verbatim}
+This will import the DSA key from the buffer ``in'' of length ``inlen'' to the ``key''.  If the process fails the function
+will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()).
+\chapter{Public Keyrings}
+\section{Introduction}
+In order to simplify the usage of the public key algorithms a set of keyring routines have been developed.  They let the
+developer manage asymmetric keys by providing load, save, export, import routines as well as encrypt, decrypt, sign, verify
+routines in a unified API.  That is all three types of PK systems can be used within the same keyring with the same API.
+To define types of keys there are four enumerations used globaly:
+\begin{verbatim}
+enum {
+NON_KEY=0,
+RSA_KEY,
+DH_KEY,
+ECC_KEY
+};
+\end{verbatim}
+To make use of the system the developer has to know how link-lists work.  The main structure that the keyring routines use
+is the ``pk\_key'' defined as:
+\begin{small}
+\begin{verbatim}
+typedef struct Pk_key {
+int     key_type,             /* PUBLIC, PRIVATE, PRIVATE_OPTIMIZED */
+system;               /* RSA, ECC or DH ?   */
+char    name[MAXLEN],         /* various info's about this key */
+email[MAXLEN],
+description[MAXLEN];
+unsigned long ID;             /* CRC32 of the name/email/description together */
+_pk_key key;
+struct Pk_key  *next;         /* linked list chain */
+} pk_key;
+\end{verbatim}
+\end{small}
+The list is chained via the ``next'' member and terminated with the node of the list that has ``system'' equal to
+{\bf NON\_KEY}.
+\section{The Keyring API}
+To initialize a blank keyring the function ``kr\_init()'' is used.
+\begin{verbatim}
+int kr_init(pk_key **pk);
+\end{verbatim}
+You pass it a pointer to a pointer of type ``pk\_key'' where it will allocate ram for one node of the keyring and sets the
+pointer.
+Now instead of calling the PK specific ``make\_key'' functions there is one function that can make all three types of keys.
+\begin{verbatim}
+int kr_make_key(pk_key *pk, prng_state *prng, int wprng,
+int system, int keysize, const char *name,
+const char *email, const char *description);
+\end{verbatim}
+The ``name'', ``email'' and ``description'' parameters are simply little pieces of information that you can tag along with a
+key.  They can each be either blank or any string less than 256 bytes.  ``system'' is one of the enumeration elements, that
+is {\bf RSA\_KEY}, {\bf DH\_KEY} or {\bf ECC\_KEY}.  ``keysize'' is the size of the key you desire which is regulated by
+the individual systems, for example, RSA keys are limited in keysize from 128 to 512 bytes.
+To find keys along a keyring there are two functions provided:
+\begin{verbatim}
+pk_key *kr_find(pk_key *pk, unsigned long ID);
+pk_key *kr_find_name(pk_key *pk, const char *name);
+\end{verbatim}
+The first searches by the 32-bit ID provided and the latter checks the name against the keyring.  They both return a pointer
+to the node in the ring of a match or {\bf NULL} if no match is found.
+To export or import a single node of a keyring the two functions are provided:
+\begin{verbatim}
+int kr_export(pk_key *pk, unsigned long ID, int key_type,
+unsigned char *out, unsigned long *outlen);
+int kr_import(pk_key *pk, const unsigned char *in);
+\end{verbatim}
+The export function exports the key with an ID provided and of a specific type much like the normal PK export routines.  The
+``key\_type'' is one of {\bf PK\_PUBLIC} or {\bf PK\_PRIVATE}.  In this function with RSA keys the type
+{\bf PK\_PRIVATE\_OPTIMIZED} is the same as the {\bf PK\_PRIVATE} type.  The import function will read in a packet and
+add it to the keyring.
+To load and save whole keyrings from disk:
+\begin{verbatim}
+int kr_load(pk_key **pk, FILE *in, symmetric_CTR *ctr);
+int kr_save(pk_key *pk, FILE *out, symmetric_CTR *ctr);
+\end{verbatim}
+Both take file pointers to allow the user to pre-append data to the stream.  The ``ctr'' parameter should be setup with
+``ctr\_start'' or set to NULL.  This parameter lets the user encrypt the keyring as its written to disk, if it is set
+to NULL the data is written without being encrypted.  The load function assumes the list has not been initialized yet
+and will reset the pointer given to it.
+There are the four encrypt, decrypt, sign and verify functions as well
+\begin{verbatim}
+int kr_encrypt_key(pk_key *pk, unsigned long ID,
+const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen,
+prng_state *prng, int wprng, int hash);
+int kr_decrypt_key(pk_key *pk, const unsigned char *in,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+The kr\_encrypt\_key() routine is designed to encrypt a symmetric key with a specified users public key.  The symmetric
+key is then used with a block cipher to encode the message.  The recipient can call kr\_decrypt\_key() to get the original
+symmetric key back and decode the message.  The hash specified must produce a message digest longer than symmetric key
+provided.
+\begin{verbatim}
+int kr_sign_hash(pk_key *pk, unsigned long ID,
+const unsigned char *in, unsigned long inlen,
+unsigned char *out, unsigned long *outlen,
+prng_state *prng, int wprng);
+int kr_verify_hash(pk_key *pk, const unsigned char *in,
+const unsigned char *hash, unsigned long hashlen,
+int *stat);
+\end{verbatim}
+Similar to the two previous these are used to sign a message digest or verify one.  This requires hashing the message
+first then passing the output in.
+To delete keys and clear rings there are:
+\begin{verbatim}
+int kr_del(pk_key **_pk, unsigned long ID);
+int kr_clear(pk_key **pk);
+\end{verbatim}
+``kr\_del'' will try to remove a key with a given ID from the ring and ``kr\_clear'' will completely empty a list and free
+the memory associated with it.  Below is small example using the keyring API:
+\begin{small}
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+pk_key *kr;
+unsigned char buf[4096], buf2[4096];
+unsigned long len;
+int err;
+/* make a new list */
+if ((err = kr_init(&kr)) != CRYPT_OK) {
+printf("kr_init: %s\n", error_to_string(err));
+exit(-1);
+}
+/* add a key to it */
+register_prng(&sprng_desc);
+if ((err = kr_make_key(kr, NULL, find_prng("sprng"), RSA_KEY, 128,
+"TomBot", "[email protected]", "test key")) == CRYPT_OK) {
+printf("kr_make_key: %s\n", error_to_string(err));
+exit(-1);
+}
+/* export the first key */
+len = sizeof(buf);
+if ((err = kr_export(kr, kr->ID, PK_PRIVATE, buf, &len)) != CRYPT_OK) {
+printf("kr_export: %s\n", error_to_string(err));
+exit(-1);
+}
+/* ... */
+}
+\end{verbatim}
+\end{small}
+\chapter{$GF(2^w)$ Math Routines}
+The library provides a set of polynomial-basis $GF(2^w)$ routines to help facilitate algorithms such as ECC over such
+fields.  Note that the current implementation of ECC in the library is strictly over the integers only.  The routines
+are simple enough to use for other purposes outside of ECC.
+At the heart of all of the GF routines is the data type ``gf\_int'.  It is simply a type definition for an array of
+$L$ 32-bit words.  You can configure the maximum size $L$ of the ``gf\_int'' type by opening the file ``mycrypt.h'' and
+changing ``LSIZE''.  Note that if you set it to $n$ then you can only multiply upto two $n \over 2$ bit polynomials without
+an overflow.  The type ``gf\_intp'' is associated with a pointer to an ``unsigned long'' as required in the algorithms.
+There are no initialization routines for ``gf\_int'' variables and you can simply use them after declaration.  There are five
+low level functions:
+\index{gf\_copy()} \index{gf\_zero()} \index{gf\_iszero()} \index{gf\_isone()}
+\index{gf\_deg()}
+\begin{verbatim}
+void gf_copy(gf_intp a, gf_intp b);
+void gf_zero(gf_intp a);
+int gf_iszero(gf_intp a);
+int gf_isone(gf_intp a);
+int gf_deg(gf_intp a);
+\end{verbatim}
+There are all fairly self-explanatory.  ``gf\_copy(a, b)'' copies the contents of ``a'' into ``b''.  ``gf\_zero()'' simply
+zeroes the entire polynomial.  ``gf\_iszero()'' tests to see if the polynomial is all zero and ``gf\_isone()'' tests to see
+if the polynomial is equal to the multiplicative identity.  ``gf\_deg()'' returns the degree of the polynomial or $-1$ if its
+a zero polynomial.
+There are five core math routines as well:
+\index{gf\_shl()} \index{gf\_shr()} \index{gf\_add()} \index{gf\_mul()} \index{gf\_div()}
+\begin{verbatim}
+void gf_shl(gf_intp a, gf_intp b);
+void gf_shr(gf_intp a, gf_intp b);
+void gf_add(gf_intp a, gf_intp b, gf_intp c);
+void gf_mul(gf_intp a, gf_intp b, gf_intp c);
+void gf_div(gf_intp a, gf_intp b, gf_intp q, gf_intp r);
+\end{verbatim}
+Which are all fairly obvious.  ``gf\_shl(a,b)'' multiplies the polynomial ``a'' by $x$ and stores it in ``b''.
+``gf\_shl(a,b)'' divides the polynomial ``a'' by $x$ and stores it in ``b''.  ``gf\_add(a,b,c)'' adds the polynomial
+``a'' to ``b'' and stores the sum in ``c''.  Similarly for ``gf\_mul(a,b,c)''.  The ``gf\_div(a,b,q,r)'' function divides
+``a'' by ``b'' and stores the quotient in ``q'' and the remainder in ``r''.
+There are six number theoretic functions as well:
+\index{gf\_mod()} \index{gf\_mulmod()} \index{gf\_invmod()} \index{gf\_gcd()} \index{gf\_is\_prime()}
+\index{gf\_sqrt()}
+\begin{verbatim}
+void gf_mod(gf_intp a, gf_intp m, gf_intp b);
+void gf_mulmod(gf_intp a, gf_intp b, gf_intp m, gf_intp c);
+void gf_invmod(gf_intp A, gf_intp M, gf_intp B);
+void gf_sqrt(gf_intp a, gf_intp m, gf_intp b);
+void gf_gcd(gf_intp A, gf_intp B, gf_intp c);
+int gf_is_prime(gf_intp a);
+\end{verbatim}
+Which all work similarly except for  ``gf\_mulmod(a,b,m,c)'' which computes $c = ab\mbox{ }(\mbox{mod }m)$.  The
+``gf\_is\_prime()'' function returns one if the polynomial is primitive, otherwise it returns zero.
+Finally to read/store a ``gf\_int'' in a binary string use:
+\index{gf\_size()} \index{gf\_toraw()} \index{gf\_readraw()}
+\begin{verbatim}
+int gf_size(gf_intp a);
+void gf_toraw(gf_intp a, unsigned char *dst);
+void gf_readraw(gf_intp a, unsigned char *str, int len);
+\end{verbatim}
+Where ``gf\_size()'' returns the size in bytes required for the data.  ``gf\_toraw(a,b)'' stores the polynomial in ``b''
+in binary format (endian neutral).  ``gf\_readraw(a,b,c)'' reads the binary string in ``b'' back.  Note that the length
+you pass it must be the same as returned by ``gf\_size()'' or it will not load correctly.
+\chapter{Miscellaneous}
+\section{Base64 Encoding and Decoding}
+The library provides functions to encode and decode a RFC1521 base64 coding scheme.  This means that it can decode what it
+encodes but the format used does not comply to any known standard.  The characters used in the mappings are:
+\begin{verbatim}
+ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
+\end{verbatim}
+Those characters should are supported in virtually any 7-bit ASCII system which means they can be used for transport over
+common e-mail, usenet and HTTP mediums.  The format of an encoded stream is just a literal sequence of ASCII characters
+where a group of four represent 24-bits of input.  The first four chars of the encoders output is the length of the
+original input.  After the first four characters is the rest of the message.
+Often it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting.  The decoder allows you to
+put any character (that is not in the above sequence) in between any character of the encoders output.  You may not however,
+break up the first four characters.
+To encode a binary string in base64 call:
+\index{base64\_encode()}  \index{base64\_decode()}
+\begin{verbatim}
+int base64_encode(const unsigned char *in, unsigned long len,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+Where ``in'' is the binary string and ``out'' is where the ASCII output is placed.  You must set the value of ``outlen'' prior
+to calling this function and it sets the length of the base64 output in ``outlen'' when it is done.  To decode a base64
+string call:
+\begin{verbatim}
+int base64_decode(const unsigned char *in, unsigned long len,
+unsigned char *out, unsigned long *outlen);
+\end{verbatim}
+\section{The Multiple Precision Integer Library (MPI)}
+The library comes with a copy of LibTomMath  which is a multiple precision integer library written by the
+author of LibTomCrypt.  LibTomMath is a trivial to use ANSI C compatible large integer library which is free
+for all uses and is distributed freely.
+At the heart of all the functions is the data type ``mp\_int'' (defined in tommath.h).  This data type is what
+will hold all large integers.  In order to use an mp\_int one must initialize it first, for example:
+\begin{verbatim}
+#include <mycrypt.h> /* mycrypt.h includes mpi.h automatically */
+int main(void)
+{
+mp_int bignum;
+/* initialize it */
+mp_init(&bignum);
+return 0;
+}
+\end{verbatim}
+If you are unfamiliar with the syntax of C the \& symbol is used to pass the address of ``bignum'' to the function.  All
+LibTomMath functions require the address of the parameters.  To free the memory of a mp\_int use (for example):
+\begin{verbatim}
+mp_clear(&bignum);
+\end{verbatim}
+The functions also have the basic form of one of the following:
+\begin{verbatim}
+mp_XXX(mp_int *a);
+mp_XXX(mp_int *a, mp_int *b, mp_int *c);
+mp_XXX(mp_int *a, mp_int *b, mp_int *c, mp_int *d);
+\end{verbatim}
+Where they perform some operation and store the result in the mp\_int variable passed on the far right.
+For example, to compute $c = a + b \mbox{ }(\mbox{mod }m)$ you would call:
+\begin{verbatim}
+mp_addmod(&a, &b, &m, &c);
+\end{verbatim}
+\subsection{Binary Forms of ``mp\_int'' Variables}
+Often it is required to store a ``mp\_int'' in binary form for transport (e.g. exporting a key, packet
+encryption, etc.).  LibTomMath includes two functions to help when exporting numbers:
+\begin{verbatim}
+int mp_raw_size(mp_int *num);
+mp_toraw(&num, buf);
+\end{verbatim}
+The former function gives the size in bytes of the raw format and the latter function actually stores the raw data.  All
+``mp\_int'' numbers are stored in big endian form (like PKCS demands) with the first byte being the sign of the number.  The
+``rsa\_exptmod()'' function differs slightly since it will take the input in the form exactly as PKCS demands (without the
+leading sign byte).  All other functions include the sign byte (since its much simpler just to include it).  The sign byte
+must be zero for positive numbers and non-zero for negative numbers.  For example,
+the sequence:
+\begin{verbatim}
+00 FF 30 04
+\end{verbatim}
+Represents the integer $255 \cdot 256^2 + 48 \cdot 256^1 + 4 \cdot 256^0$ or 16,723,972.
+To read a binary string back into a ``mp\_int'' call:
+\begin{verbatim}
+mp_read_raw(mp_int *num, unsigned char *str, int len);
+\end{verbatim}
+Where ``num'' is where to store it, ``str'' is the binary string (including the leading sign byte) and ``len'' is the
+length of the binary string.
+\subsection{Primality Testing}
+\index{Primality Testing}
+The library includes primality testing and random prime functions as well.  The primality tester will perform the test in
+two phases.  First it will perform trial division by the first few primes.  Second it will perform eight rounds of the
+Rabin-Miller primality testing algorithm.  If the candidate passes both phases it is declared prime otherwise it is declared
+composite.  No prime number will fail the two phases but composites can.  Each round of the Rabin-Miller algorithm reduces
+the probability of a pseudo-prime by $1 \over 4$ therefore after sixteen rounds the probability is no more than
+$\left ( { 1 \over 4 } \right )^{8} = 2^{-16}$.  In practice the probability of error is in fact much lower than that.
+When making random primes the trial division step is in fact an optimized implementation of ``Implementation of Fast RSA Key Generation on Smart Cards''\footnote{Chenghuai Lu, Andre L. M. dos Santos and Francisco R. Pimentel}.
+In essence a table of machine-word sized residues are kept of a candidate modulo a set of primes.  When the candiate
+is rejected and ultimately incremented to test the next number the residues are updated without using multi-word precision
+math operations.  As a result the routine can scan ahead to the next number required for testing with very little work
+involved.
+In the event that a composite did make it through it would most likely cause the the algorithm trying to use it to fail.  For
+instance, in RSA two primes $p$ and $q$ are required.  The order of the multiplicative sub-group (modulo $pq$) is given
+as $\phi(pq)$ or $(p - 1)(q - 1)$.  The decryption exponent $d$ is found as $de \equiv 1\mbox{ }(\mbox{mod } \phi(pq))$.  If either $p$ or $q$ is composite the value of $d$ will be incorrect and the user
+will not be able to sign or decrypt messages at all.  Suppose $p$ was prime and $q$ was composite this is just a variation of
+the multi-prime RSA.  Suppose $q = rs$ for two primes $r$ and $s$ then $\phi(pq) = (p - 1)(r - 1)(s - 1)$ which clearly is
+not equal to $(p - 1)(rs - 1)$.
+These are not technically part of the LibTomMath library but this is the best place to document them.
+To test if a ``mp\_int'' is prime call:
+\begin{verbatim}
+int is_prime(mp_int *N, int *result);
+\end{verbatim}
+This puts a one in ``result'' if the number is probably prime, otherwise it places a zero in it.  It is assumed that if
+it returns an error that the value in ``result'' is undefined.  To make
+a random prime call:
+\begin{verbatim}
+int rand_prime(mp_int *N, unsigned long len, prng_state *prng, int wprng);
+\end{verbatim}
+Where ``len'' is the size of the prime in bytes ($2 \le len \le 256$).  You can set ``len'' to the negative size you want
+to get a prime of the form $p \equiv 3\mbox{ }(\mbox{mod } 4)$.  So if you want a 1024-bit prime of this sort pass
+``len = -128'' to the function.  Upon success it will return {\bf CRYPT\_OK} and ``N'' will contain an integer which
+is very likely prime.
+\chapter{Programming Guidelines}
+\section{Secure Pseudo Random Number Generators}
+Probably the singal most vulnerable point of any cryptosystem is the PRNG.  Without one generating and protecting secrets
+would be impossible.  The requirement that one be setup correctly is vitally important and to address this point the library
+does provide two RNG sources that will address the largest amount of end users as possible.  The ``sprng'' PRNG provided
+provides and easy to access source of entropy for any application on a *NIX or Windows computer.
+However, when the end user is not on one of these platforms the application developer must address the issue of finding
+entropy.  This manual is not designed to be a text on cryptography.  I would just like to highlight that when you design
+a cryptosystem make sure the first problem you solve is getting a fresh source of entropy.
+\section{Preventing Trivial Errors}
+Two simple ways to prevent trivial errors is to prevent overflows and to check the return values.  All of the functions
+which output variable length strings will require you to pass the length of the destination.  If the size of your output
+buffer is smaller than the output it will report an error.  Therefore, make sure the size you pass is correct!
+Also virtually all of the functions return an error code or {\bf CRYPT\_OK}.  You should detect all errors as simple
+typos or such can cause algorithms to fail to work as desired.
+\section{Registering Your Algorithms}
+To avoid linking and other runtime errors it is important to register the ciphers, hashes and PRNGs you intend to use
+before you try to use them.  This includes any function which would use an algorithm indirectly through a descriptor table.
+A neat bonus to the registry system is that you can add external algorithms that are not part of the library without
+having to hack the library.  For example, suppose you have a hardware specific PRNG on your system.  You could easily
+write the few functions required plus a descriptor.  After registering your PRNG all of the library functions that
+need a PRNG can instantly take advantage of it.
+\section{Key Sizes}
+\subsection{Symmetric Ciphers}
+For symmetric ciphers use as large as of a key as possible.  For the most part ``bits are cheap'' so using a 256-bit key
+is not a hard thing todo.
+\subsection{Assymetric Ciphers}
+The following chart gives the work factor for solving a DH/RSA public key using the NFS.  The work factor for a key of order
+$n$ is estimated to be
+\begin{equation}
+e^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}}
+\end{equation}
+Note that $n$ is not the bit-length but the magnitude.  For example, for a 1024-bit key $n = 2^{1024}$.  The work required
+is:
+\begin{center}
+\begin{tabular}{|c|c|}
+\hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\
+\hline 512 & 63.92 \\
+\hline 768 & 76.50 \\
+\hline 1024 & 86.76 \\
+\hline 1536 & 103.37 \\
+\hline 2048 & 116.88 \\
+\hline 2560 & 128.47 \\
+\hline 3072 & 138.73 \\
+\hline 4096 & 156.49 \\
+\hline
+\end{tabular}
+\end{center}
+The work factor for ECC keys is much higher since the best attack is still fully exponentional.  Given a key of magnitude
+$n$ it requires $\sqrt n$ work.  The following table sumarizes the work required:
+\begin{center}
+\begin{tabular}{|c|c|}
+\hline ECC Key Size (bits) & Work Factor ($log_2$) \\
+\hline 160 & 80  \\
+\hline 192 & 96  \\
+\hline 224 & 112 \\
+\hline 256 & 128 \\
+\hline 384 & 192 \\
+\hline 521 & 260.5 \\
+\hline
+\end{tabular}
+\end{center}
+Using the above tables the following suggestions for key sizes seems appropriate:
+\begin{center}
+\begin{tabular}{|c|c|c|}
+\hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\
+\hline Short term (less than a year) & 1024 & 160 \\
+\hline Short term (less than five years) & 1536 & 192 \\
+\hline Long Term (less than ten years) & 2560 & 256 \\
+\hline
+\end{tabular}
+\end{center}
+\section{Thread Safety}
+The library is not thread safe but several simple precautions can be taken to avoid any problems.  The registry functions
+such as register\_cipher() are not thread safe no matter what you do.  Its best to call them from your programs initializtion
+code before threads are initiated.
+The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc.  This means that if each
+thread has its own state variables then they will not affect each other.  This is fairly simple with symmetric ciphers
+and hashes.  However, the keyring and PRNG support is something the threads will want to share.  The simplest workaround
+is create semaphores or mutexes around calls to those functions.
+Since C does not have standard semaphores this support is not native to Libtomcrypt.  Even a C based semaphore is not entire
+possible as some compilers may ignore the ``volatile'' keyword or have multiple processors.  Provide your host application
+is modular enough putting the locks in the right place should not bloat the code significantly and will solve all thread
+safety issues within the library.
+\chapter{Configuring the Library}
+\section{Introduction}
+The library is fairly flexible about how it can be built, used and generally distributed.  Additions are being made with
+each new release that will make the library even more flexible.  Most options are placed in the makefile and others
+are in ``mycrypt\_cfg.h''.  All are used when the library is built from scratch.
+For GCC platforms the file ``makefile'' is the makefile to be used.  On MSVC platforms ``makefile.vc'' and on PS2 platforms
+``makefile.ps2''.
+\section{mycrypt\_cfg.h}
+The file ``mycrypt\_cfg.h'' is what lets you control what functionality you want to remove from the library.  By default,
+everything the library has to offer it built.
+\subsubsection{ARGTYPE}
+This lets you control how the \_ARGCHK macro will behave.  The macro is used to check pointers inside the functions against
+NULL.  There are three settings for ARGTYPE.  When set to 0 it will have the default behaviour of printing a message to
+stderr and raising a SIGABRT signal.  This is provided so all platforms that use libtomcrypt can have an error that functions
+similarly.  When set to 1 it will simply pass on to the assert() macro.  When set to 2 it will resolve to a empty macro
+and no error checking will be performed.
+\subsubsection{Endianess}
+There are five macros related to endianess issues.  For little endian platforms define, ENDIAN\_LITTLE.  For big endian
+platforms define ENDIAN\_BIG.  Similarly when the default word size of an ``unsigned long'' is 32-bits define ENDIAN\_32BITWORD
+or define ENDIAN\_64BITWORD when its 64-bits.  If you do not define any of them the library will automatically use ENDIAN\_NEUTRAL
+which will work on all platforms.  Currently the system will automatically detect GCC or MSVC on a windows platform as well
+as GCC on a PS2 platform.
+\section{The Configure Script}
+There are also options you can specify from the configure script or ``mycrypt\_config.h''.
+\subsubsection{X memory routines}
+The makefiles must define three macros denoted as XMALLOC, XCALLOC and XFREE which resolve to the name of the respective
+functions.  This lets you substitute in your own memory routines.  If you substitute in your own functions they must behave
+like the standard C library functions in terms of what they expect as input and output.  By default the library uses the
+standard C routines.
+\subsubsection{X clock routines}
+The rng\_get\_bytes() function can call a function that requires the clock() function.  These macros let you override
+the default clock() used with a replacement.  By default the standard C library clock() function is used.
+\subsubsection{NO\_FILE}
+During the build if NO\_FILE is defined then any function in the library that uses file I/O will not call the file I/O
+functions and instead simply return CRYPT\_ERROR.  This should help resolve any linker errors stemming from a lack of
+file I/O on embedded platforms.
+\subsubsection{CLEAN\_STACK}
+When this functions is defined the functions that store key material on the stack will clean up afterwards.  Assumes that
+you have no memory paging with the stack.
+\subsubsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions}
+There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly self-explanatory.
+When they are defined the functionality is included otherwise it is not.  There are some dependency issues which are
+noted in the file.  For instance, Yarrow requires CTR chaining mode, a block cipher and a hash function.
+\subsubsection{TWOFISH\_SMALL and TWOFISH\_TABLES}
+Twofish is a 128-bit symmetric block cipher that is provided within the library.  The cipher itself is flexible enough
+to allow some tradeoffs in the implementation.  When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish
+requires only 200 bytes of memory.  This is achieved by not pre-computing the substitution boxes.  Having this
+defined will also greatly slow down the cipher.  When this macro is not defined Twofish will pre-compute the
+tables at a cost of 4KB of memory.  The cipher will be much faster as a result.
+When TWOFISH\_TABLES is defined the cipher will use pre-computed (and fixed in code) tables required to work.  This is
+useful when TWOFISH\_SMALL is defined as the table values are computed on the fly.  When this is defined the code size
+will increase by approximately 500 bytes.  If this is defined but TWOFISH\_SMALL is not the cipher will still work but
+it will not speed up the encryption or decryption functions.
+\subsubsection{SMALL\_CODE}
+When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants.
+These variants are slower but can save quite a bit of code space.
+\end{document}

Mercurial > dropbear

comparison crypt.tex @ 3:7faae8f46238 libtomcrypt-orig