dropbear: crypt.tex comparison

comparison crypt.tex @ 143:5d99163f7e32 libtomcrypt-orig

import of libtomcrypt 0.99

author	Matt Johnston <matt@ucc.asn.au>
date	Sun, 19 Dec 2004 11:34:45 +0000
parents	6362d3854bb4
children	1c15b283127b

comparison

equal deleted inserted replaced

-:6362d3854bb4
+:5d99163f7e32
-\documentclass[b5paper]{book}
+\documentclass[a4paper]{book}
 \usepackage{hyperref}
 \usepackage{makeidx}
 \usepackage{amssymb}
 \usepackage{color}
 \usepackage{alltt}
 \def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}}
 \def\gap{\vspace{0.5ex}}
 \makeindex
 \begin{document}
-\title{A Tiny Crypto Library, \\ LibTomCrypt \\ Version 0.96}
+\title{LibTomCrypt \\ Version 0.99}
 \author{Tom St Denis \\
 \\
 [email protected] \\
-http://libtomcrypt.org \\ \\
+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.
+formatted for A4 paper using the \LaTeX{} {\em book} macro package.
 \vspace{10cm}
 \begin{flushright}Open Source.  Open Academia.  Open Minds.
 \mbox{ }
 Tom St Denis,
-Ontario, Canada
+Phone: 1-613-836-3160
+111 Banning Rd
+Kanata, Ontario
+K2L 1C3
+Canada
 \end{flushright}
 \newpage
 \tableofcontents
 \chapter{Introduction}
 \section{What is the LibTomCrypt?}
 `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.
+was written by Richard De Moliner ([email protected]) and seems to be free for use.
 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
+They can be removed from a build by simply commenting out the two appropriate lines in ``mycrypt\_custom.h''.  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:
+I would like to give thanks to the following people (in no particular order) for helping me develop this project from
+early on:
 \begin{enumerate}
 \item Richard van de Laarschot
 \item Richard Heathfield
 \item Ajay K. Agrawal
 \item Brian Gladman
 \item Wayne Scott
 \item Andrew Tyler
 \item Sky Schulz
 \item Christopher Imes
 \end{enumerate}
+There have been quite a few other people as well.  Please check the change log to see who else has contributed from
+time to time.
 \chapter{The Application Programming Interface (API)}
 \section{Introduction}
 \index{CRYPT\_ERROR} \index{CRYPT\_OK}
 \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 undefined & defined & Faster keysetup, larger code. \\
 \hline defined & undefined & Very slow, 0.2KB of ram. \\
-\hline defined & defined & Somewhat faster, 0.2KB of ram, larger code. \\
+\hline defined & defined & Faster, 0.2KB of ram, larger code. \\
 \hline
 \end{tabular}
 \end{center}
 \end{small}
 printf("Unable to register Blowfish cipher.");
 return -1;
 }
 /* generic call to function (assuming the key in key[] was already setup) */
-if ((err = cipher_descriptor[find_cipher("blowfish")].setup(key, 8, 0, &skey)) != CRYPT_OK) {
+if ((err = cipher_descriptor[find_cipher("blowfish")].setup(key, 8, 0, &skey)) !=
+CRYPT_OK) {
 printf("Error setting up Blowfish: %s\n", error_to_string(err));
 return -1;
 }
 /* ... use cipher ... */
 }
 /* somehow fill out key and IV */
 /* start up CTR mode */
-if ((err = ctr_start(find_cipher("twofish"), /* index of desired cipher */
+if ((err = ctr_start(
-IV, /* the initial vector */
+find_cipher("twofish"), /* index of desired cipher */
-key, /* the secret key */
+IV, /* the initial vector */
-16, /* length of secret key (16 bytes, 128 bits) */
+key, /* the secret key */
-0, /* 0 == default # of rounds */
+16, /* length of secret key (16 bytes, 128 bits) */
-&ctr)  /* where to store initialized CTR state */
+0, /* 0 == default # of rounds */
+&ctr)  /* where to store initialized CTR state */
 ) != CRYPT_OK) {
 printf("ctr_start error: %s\n", error_to_string(err));
 return -1;
 }
 \begin{verbatim}
 int register_hash(const struct _hash_descriptor *hash);
 int unregister_hash(const struct _hash_descriptor *hash);
 \end{verbatim}
-\subsection{Notice}
+\section{Cipher Hash Construction}
+\index{Cipher Hash Construction}
+An addition to the suite of hash functions is the ``Cipher Hash Construction'' or ``CHC'' mode.  In this mode
+applicable block ciphers (such as AES) can be turned into hash functions that other LTC functions can use.  In
+particular this allows a cryptosystem to be designed using very few moving parts.
+In order to use the CHC system the developer will have to take a few extra steps.  First the ``chc\_desc'' hash
+descriptor must be registered with register\_hash().  At this point the CHC hash cannot be used to hash
+data.  While it is in the hash system you still have to tell the CHC code which cipher to use.  This is accomplished
+via the chc\_register() function.
+\index{chc\_register()}
+\begin{verbatim}
+int chc_register(int cipher);
+\end{verbatim}
+A cipher has to be registered with CHC (and also in the cipher descriptor tables with
+register\_cipher()).  The chc\_register() function will bind a cipher to the CHC system.  Only one cipher can
+be bound to the CHC hash at a time.  There are additional requirements for the system to work.
+\begin{enumerate}
+\item The cipher must have a block size greater than 64--bits.
+\item The cipher must allow an input key the size of the block size.
+\end{enumerate}
+Example of using CHC with the AES block cipher.
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+int err;
+/* register cipher and hash */
+if (register_cipher(&aes_enc_desc) == -1) {
+printf("Could not register cipher\n");
+return EXIT_FAILURE;
+}
+if (register_hash(&chc_desc) == -1) {
+printf("Could not register hash\n");
+return EXIT_FAILURE;
+}
+/* start chc with AES */
+if ((err = chc_register(find_cipher("aes"))) != CRYPT_OK) {
+printf("Error binding AES to CHC: %s\n", error_to_string(err));
+}
+/* now you can use chc_hash in any LTC function [aside from pkcs...] */
+/* ... */
+\end{verbatim}
+\section{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
 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:
+\index{PRNG start}
 \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:
+\index{PRNG add\_entropy}
 \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.
+\index{PRNG ready}
 \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:
+\index{PRNG read}
 \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.
+Which returns the number of bytes read from the PRNG.  When you are finished with a PRNG state you call
+the following.
+\index{PRNG done}
+\begin{verbatim}
+void XXX_done(prng_state *prng);
+\end{verbatim}
+This will terminate a PRNG state and free any memory (if any) allocated.  To export a PRNG state
+so that you can later resume the PRNG call the following.
+\index{PRNG export}
+\begin{verbatim}
+int XXX_export(unsigned char *out, unsigned long *outlen,
+prng_state    *prng);
+\end{verbatim}
+This will write a ``PRNG state'' to the buffer ``out'' of length ``outlen'' bytes.  The idea of
+the export is meant to be used as a ``seed file''.  That is, when the program starts up there will not likely
+be that much entropy available.   To import a state to seed a PRNG call the following function.
+\index{PRNG import}
+\begin{verbatim}
+int XXX_import(const unsigned char *in, unsigned long inlen,
+prng_state     *prng);
+\end{verbatim}
+This will call the start and add\_entropy functions of the given PRNG.  It will use the state in
+``in'' of length ``inlen'' as the initial seed.  You must pass the same seed length as was exported
+by the corresponding export function.
+Note that importing a state will not ``resume'' the PRNG from where it left off.  That is, if you export
+a state, emit (say) 8 bytes and then import the previously exported state the next 8 bytes will not
+specifically equal the 8 bytes you generated previously.
+When a program is first executed the normal course of operation is
+\begin{enumerate}
+\item Gather entropy from your sources for a given period of time or number of events.
+\item Start, use your entropy via add\_entropy and ready the PRNG yourself.
+\end{enumerate}
+When your program is finished you simply call the export function and save the state to a medium (disk,
+flash memory, etc).  The next time your application starts up you can detect the state, feed it to the
+import function and go on your way.  It is ideal that (as soon as possible) after startup you export a
+fresh state.  This helps in the case that the program aborts or the machine is powered down without
+being given a chance to exit properly.
+Note that even if you have a state to import it is important to add new entropy to the state.  However,
+there is less pressure to do so.
+To test a PRNG for operational conformity call the following functions.
+\index{PRNG test}
+\begin{verbatim}
+int XXX_test(void);
+\end{verbatim}
+This will return \textbf{CRYPT\_OK} if PRNG is operating properly.
 \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
+Below is a simple snippet to read 10 bytes from yarrow.  Its important to note that this snippet is
-the entropy added is not random.
+{\bf NOT} secure since the entropy added is not random.
 \begin{verbatim}
 #include <mycrypt.h>
 int main(void)
 {
 \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  export_size;    /* size in bytes of exported state */
 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 *);
+void (*done)(prng_state *);
+int (*export)(unsigned char *, unsigned long *, prng_state *);
+int (*import)(const unsigned char *, unsigned long, prng_state *);
+int (*test)(void);
 };
 \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.
 \begin{verbatim}
 int register_prng(const struct _prng_descriptor *prng);
 int unregister_prng(const struct _prng_descriptor *prng);
 \end{verbatim}
-\subsubsection{PRNGs Provided}
+\subsection{PRNGs Provided}
-Currently Yarrow (yarrow\_desc), RC4 (rc4\_desc) and the secure RNG (sprng\_desc) are provided as PRNGs within the
+\begin{figure}[here]
-library.
+\begin{center}
+\begin{small}
-RC4 is provided with a PRNG interface because it is a stream cipher and not well suited for the symmetric block cipher
+\begin{tabular}{|c|c|l|}
-interface.  You provide the key for RC4 via the rc4\_add\_entropy() function.  By calling rc4\_ready() the key will be used
+\hline \textbf{Name} & \textbf{Descriptor} & \textbf{Usage} \\
-to setup the RC4 state for encryption or decryption.  The rc4\_read() function has been modified from RC4 since it will
+\hline Yarrow & yarrow\_desc & Fast short-term PRNG \\
-XOR the output of the RC4 keystream generator against the input buffer you provide.  The following snippet will demonstrate
+\hline Fortuna & fortuna\_desc & Fast long-term PRNG (recommended) \\
-how to encrypt a buffer with RC4:
+\hline RC4 & rc4\_desc & Stream Cipher \\
+\hline SOBER-128 & sober128\_desc & Stream Cipher (also very fast PRNG) \\
+\hline
+\end{tabular}
+\end{small}
+\end{center}
+\caption{List of Provided PRNGs}
+\end{figure}
+\subsubsection{Yarrow}
+Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources
+(keyboard, mouse, interrupts, etc) and produce an unbounded string of random bytes.
+\textit{Note:} This PRNG is still secure for most taskings but is no longer recommended.  Users
+should use Fortuna instead.
+\subsubsection{Fortuna}
+Fortuna is a fast attack tolerant and more thoroughly designed PRNG suitable for long term
+usage.  It is faster than the default implementation of Yarrow\footnote{Yarrow has been implemented
+to work with most cipher and hash combos based on which you have chosen to build into the library.} while
+providing more security.
+Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher
+and SHA--256 hash function.  Technically Fortuna will work with any block cipher that accepts a 256--bit
+key and any hash that produces at least a 256--bit output.  However, to make the implementation simpler
+it has been fixed to those choices.
+Fortuna is more secure than Yarrow in the sense that attackers who learn parts of the entropy being
+added to the PRNG learn far less about the state than that of Yarrow.  Without getting into to many
+details Fortuna has the ability to recover from state determination attacks where the attacker starts
+to learn information from the PRNGs output about the internal state.  Yarrow on the other hand cannot
+recover from that problem until new entropy is added to the pool and put to use through the ready() function.
+\subsubsection{RC4}
+RC4 is an old stream cipher that can also double duty as a PRNG in a pinch.  You ``key'' it by
+calling add\_entropy() and setup the key by calling ready().  You can only add upto 256 bytes via
+add\_entropy().
+When you read from RC4 the output of the RC4 algorithm is XOR'd against your buffer you provide.  In this
+manner you can use rc4\_read() as an encrypt (and decrypt) function.
+You really shouldn't use RC4 anymore.  This isn't because RC4 is weak (though biases are known to exist) just
+simply that faster alternatives exist.
+\subsubsection{SOBER-128}
+SOBER-128 is a stream cipher designed by the QUALCOMM Australia team.  Like RC4 you ``key'' it by
+calling add\_entropy().  There is no need to call ready() for this PRNG as it does not do anything.
+Note that this cipher has several oddities about how it operates.  The first time you call
+add\_entropy() that sets the cipher's key.  Every other time you call the same function it sets
+the cipher's IV variable.  The IV mechanism allows you to encrypt several messages with the same
+key and not re--use the same key material.
+Unlike Yarrow and Fortuna all of the entropy (and hence security) of this algorithm rests in the data
+you pass it on the first call to add\_entropy().  All buffers sent to add\_entropy() must have a length
+that is a multiple of four bytes.
+Like RC4 the output of SOBER--128 is XOR'ed against the buffer you provide it.  In this manner you can use
+sober128\_read() as an encrypt (and decrypt) function.
+Since SOBER-128 has a fixed keying scheme and is very fast (faster than RC4) the ideal usage of SOBER-128 is to
+key it from the output of Fortuna (or Yarrow) and use it to encrypt messages.  It is also ideal for
+simulations which need a high quality (and fast) stream of bytes.
+\subsubsection{Example Usage}
 \begin{small}
 \begin{verbatim}
 #include <mycrypt.h>
 int main(void)
 {
 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
+\index{PK\_PRIVATE} \index{PK\_PUBLIC}
-two are private keys where the ``optimized'' type uses the Chinese Remainder Theorem to speed up decryption/signatures.  By
+There are two types of RSA keys.  The types are {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}.  The first type is a private
-default all new keys are of the ``optimized'' type.  The non-optimized private type is provided for backwards compatibility
+RSA key which includes the CRT parameters\footnote{As of v0.99 the PK\_PRIVATE\_OPTIMIZED type has been deprecated
-as well as to save space since the optimized key requires about four times as much memory.
+and has been replaced by the PK\_PRIVATE type.} in the form of a RSAPrivateKey.  The second type is a public RSA key
+which only includes the modulus and public exponent.  It takes the form of a RSAPublicKey.
 \subsection{RSA Exponentiation}
 To do raw work with the RSA function call:
 \index{rsa\_exptmod()}
 }
 /* if all went well pt == pt2, l2 == 16, res == 1 */
 }
 \end{verbatim}
-\chapter{Password Based Cryptography}
-\section{PKCS \#5}
+\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.
+\index{dh\_encrypt\_key()} \index{dh\_decrypt\_key()}
+\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.
+\index{dh\_sign\_hash()} \index{dh\_verify\_hash()}
+\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.
+\index{ecc\_encrypt\_key()} \index{ecc\_decrypt\_key()}
+\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.
+\index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()}
+\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.
+\index{dsa\_free()}
+\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.
+\index{dsa\_verify\_key()}
+\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
+\index{dsa\_sign\_hash()}
+\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
+\index{dsa\_verify\_hash()}
+\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
+\index{dsa\_export()}
+\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
+\index{dsa\_import()}
+\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{Standards Support}
+\section{DER Support}
+DER or ``Distinguished Encoding Rules'' is a subset of the ASN.1 encoding rules that is fully deterministic and
+ideal for cryptography.  In particular ASN.1 specifies an INTEGER type for storing arbitrary sized integers.  DER
+further limits the ASN.1 specifications to a deterministic encoding.
+\subsection{Storing INTEGER types}
+\index{der\_encode\_integer()}
+\begin{alltt}
+int der_encode_integer(mp_int *num, unsigned char *out, unsigned long *outlen);
+\end{alltt}
+This will store the integer in ``num'' to the output buffer ``out'' of length ``outlen''.  It only stores
+non--negative numbers.  It stores the number of octets used back in ``outlen''.
+\subsection{Reading INTEGER types}
+\index{der\_decode\_integer()}
+\begin{alltt}
+int der_decode_integer(const unsigned char *in, unsigned long *inlen, mp_int *num);
+\end{alltt}
+This will decode the DER encoded INTEGER in ``in'' of length ``inlen'' and store the resulting integer
+in ``num''.  It will store the bytes read in ``inlen'' which is handy if you have to parse multiple
+data items out of a binary packet.
+\subsection{INTEGER length}
+\index{der\_length\_integer()}
+\begin{alltt}
+int der_length_integer(mp_int *num, unsigned long *len);
+\end{alltt}
+This will determine the length of the DER encoding of the integer ``num'' and store it in ``len''.
+\subsection{Multiple INTEGER types}
+To simplify the DER encoding/decoding there are two functions two handle multple types at once.
+\index{der\_put\_multi\_integer()}
+\index{der\_get\_multi\_integer()}
+\begin{alltt}
+int der_put_multi_integer(unsigned char *dst, unsigned long *outlen, mp_int *num, ...);
+int der_get_multi_integer(const unsigned char *src, unsigned long *inlen,  mp_int *num, ...);
+\end{alltt}
+These will handle multiple encodings/decodings at once.  They work like their single operand counterparts
+except they handle a \textbf{NULL} terminated list of operands.
+\begin{verbatim}
+#include <mycrypt.h>
+int main(void)
+{
+mp_int        a, b, c, d;
+unsigned char buffer[1000];
+unsigned long len;
+int           err;
+/* init a,b,c,d with some values ... */
+/* ok we want to store them now... */
+len = sizeof(buffer);
+if ((err = der_put_multi_integer(buffer, &len,
+&a, &b, &c, &d, NULL)) != CRYPT_OK) {
+// error
+}
+printf("I stored %lu bytes in buf\n", len);
+/* ok say we want to get them back for fun */
+/* len set previously...otherwise set it to the size of the packet */
+if ((err = der_get_multi_integer(buffer, &len,
+&a, &b, &c, &d, NULL)) != CRYPT_OK) {
+// error
+}
+printf("I read %lu bytes from buf\n", len);
+}
+\end{verbatim}
+\section{Password Based Cryptography}
+\subsection{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}
+\subsection{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.
 \index{pkcs\_5\_alg1()}
 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}
+\subsection{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.
 /* use material (recall to store the salt in the output) */
 \}
 \end{alltt}
-\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.
-\index{dh\_encrypt\_key()} \index{dh\_decrypt\_key()}
-\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.
-\index{dh\_sign\_hash()} \index{dh\_verify\_hash()}
-\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.
-\index{ecc\_encrypt\_key()} \index{ecc\_decrypt\_key()}
-\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.
-\index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()}
-\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.
-\index{dsa\_free()}
-\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.
-\index{dsa\_verify\_key()}
-\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
-\index{dsa\_sign\_hash()}
-\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
-\index{dsa\_verify\_hash()}
-\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
-\index{dsa\_export()}
-\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
-\index{dsa\_import()}
-\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{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:
 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}
+\chapter{Configuring and Building 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
+each new release that will make the library even more flexible.  Each of the classes of functions can be disabled during
-are in ``mycrypt\_cfg.h''.  All are used when the library is built from scratch.
+the build process to make a smaller library.  This is particularly useful for shared libraries.
-For GCC platforms the file ``makefile'' is the makefile to be used.  On MSVC platforms ``makefile.vc'' and on PS2 platforms
+\section{Building a Static Library}
-``makefile.ps2''.
+The library can be built as a static library which is generally the simplest and most portable method of
+building the library.  With a CC or GCC equipped platform you can issue the following
+\begin{alltt}
+make install_lib
+\end{alltt}
+Which will build the library and install it in /usr/lib (as well as the headers in /usr/include).  The destination
+directory of the library and headers can be changed by editing ``makefile''.  The variable LIBNAME controls
+where the library is to be installed and INCNAME controls where the headers are to be installed.  A developer can
+then use the library by including ``mycrypt.h'' in their program and linking against ``libtomcrypt.a''.
+A static library can also be built with the Intel C Compiler  (ICC) by issuing the following
+\begin{alltt}
+make -f makefile.icc install
+\end{alltt}
+This will also build ``libtomcrypt.a'' except that it will use ICC.  Additionally Microsoft's Visual C 6.00 can be used
+by issuing
+\begin{alltt}
+nmake -f makefile.msvc
+\end{alltt}
+You will have to manually copy ``tomcrypt.lib'' and the headers to your MSVC lib/inc directories.
+\subsection{MPI Control}
+If you already have LibTomMath installed you can safely remove it from the build.  By commenting the line
+in the appropriate makefile which starts with
+\begin{alltt}
+MPIOBJECT=mpi
+\end{alltt}
+Simply place a \# at the start and re-build the library.  To properly link applications you will have to also
+link in LibTomMath.  Removing MPI has the benefit of cutting down the library size as well potentially have access
+to the latest mpi.
+\section{Building a Shared Library}
+LibTomCrypt can also be built as a shared library (.so, .dll, etc...).  With non-Windows platforms the assumption
+of the presence of gcc and ``libtool'' has been made.  These are fairly common on Unix/Linux/BSD platforms.  To
+build a .so shared library issue
+\begin{alltt}
+make -f makefile.shared
+\end{alltt}
+This will use libtool and gcc to build a shared library ``libtomcrypt.la'' as well as a static library ``libtomcrypt.a''
+and install them into /usr/lib (and the headers into /usr/include).  To link your application you should use the
+libtool program in ``--mode=link''.
+You can also build LibTomCrypt as a shared library (DLL) in Windows with Cygwin.  Issue the following
+\begin{alltt}
+make -f makefile.cygwin_dll
+\end{alltt}
+This will build ``libtomcrypt.dll.a'' which is an import library for ``libtomcrypt.dll''.  You must copy
+``libtomcrypt.dll.a'' to your library directory, ``libtomcrypt.dll' to somewhere in your PATH and the header
+files to your include directory.  So long as ``libtomcrypt.dll'' is in your system path you can run any LibTomCrypt
+program that uses it.
 \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,
+The file ``mycrypt\_cfg.h'' is what lets you control various high level macros which control the behaviour
-everything the library has to offer it built.
+of the library.
 \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
 \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
+which will work on all platforms.
-as GCC on a PS2 platform.
+Currently LibTomCrypt will detect x86-32 and x86-64 running GCC as well as x86-32 running MSVC.
 \section{The Configure Script}
-There are also options you can specify from the configure script or ``mycrypt\_config.h''.
+There are also options you can specify from the configure script or ``mycrypt\_custom.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
+At the top of mycrypt\_custom.h are four macros denoted as XMALLOC, XCALLOC, XREALLOC and XFREE which resolve to
-functions.  This lets you substitute in your own memory routines.  If you substitute in your own functions they must behave
+the name of the respective functions.  This lets you substitute in your own memory routines.  If you substitute in
-like the standard C library functions in terms of what they expect as input and output.  By default the library uses the
+your own functions they must behave like the standard C library functions in terms of what they expect as input and
-standard C routines.
+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
+functions and instead simply return CRYPT\_NOP.  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
+When this functions is defined the functions that store key material on the stack will clean up afterwards.
-you have no memory paging with the stack.
+Assumes that you have no memory paging with the stack.
+\subsubsection{LTC\_TEST}
+When this has been defined the various self--test functions (for ciphers, hashes, prngs, etc) are included in the build.
+When this has been undefined the tests are removed and if called will return CRYPT\_NOP.
 \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.
+There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly
-When they are defined the functionality is included otherwise it is not.  There are some dependency issues which are
+self-explanatory.  When they are defined the functionality is included otherwise it is not.  There are some
-noted in the file.  For instance, Yarrow requires CTR chaining mode, a block cipher and a hash function.
+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
 \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.
+\section{MPI Tweaks}
+\subsection{RSA Only Tweak}
+If you plan on only using RSA with moduli in the range of 1024 to 2560 bits you can enable a series of tweaks
+to reduce the library size.  Follow these steps
+\begin{enumerate}
+\item Undefine MDSA, MECC and MDH from mycrypt\_custom.h
+\item Undefine LTM\_ALL  from tommath\_superclass.h
+\item Define SC\_RSA\_1 from tommath\_superclass.h
+\item Rebuild the library.
+\end{enumerate}
 \input{crypt.ind}
 \end{document}

Mercurial > dropbear

comparison crypt.tex @ 143:5d99163f7e32 libtomcrypt-orig