• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1\documentclass[synpaper]{book}
2\usepackage[dvips]{geometry}
3\usepackage{hyperref}
4\usepackage{makeidx}
5\usepackage{amssymb}
6\usepackage{color}
7\usepackage{alltt}
8\usepackage{graphicx}
9\usepackage{layout}
10\usepackage{fancyhdr}
11\def\union{\cup}
12\def\intersect{\cap}
13\def\getsrandom{\stackrel{\rm R}{\gets}}
14\def\cross{\times}
15\def\cat{\hspace{0.5em} \| \hspace{0.5em}}
16\def\catn{$\|$}
17\def\divides{\hspace{0.3em} | \hspace{0.3em}}
18\def\nequiv{\not\equiv}
19\def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}}
20\def\lcm{{\rm lcm}}
21\def\gcd{{\rm gcd}}
22\def\log{{\rm log}}
23\def\ord{{\rm ord}}
24\def\abs{{\mathit abs}}
25\def\rep{{\mathit rep}}
26\def\mod{{\mathit\ mod\ }}
27\renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})}
28\newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor}
29\newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil}
30\def\Or{{\rm\ or\ }}
31\def\And{{\rm\ and\ }}
32\def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}}
33\def\implies{\Rightarrow}
34\def\undefined{{\rm \textit{undefined}}}
35\def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}}
36\let\oldphi\phi
37\def\phi{\varphi}
38\def\Pr{{\rm Pr}}
39\newcommand{\str}[1]{{\mathbf{#1}}}
40\def\F{{\mathbb F}}
41\def\N{{\mathbb N}}
42\def\Z{{\mathbb Z}}
43\def\R{{\mathbb R}}
44\def\C{{\mathbb C}}
45\def\Q{{\mathbb Q}}
46\definecolor{DGray}{gray}{0.5}
47\newcommand{\emailaddr}[1]{\mbox{$<${#1}$>$}}
48\def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}}
49\def\gap{\vspace{0.5ex}}
50\makeindex
51\newcommand{\mysection}[1]    % Re-define the chaptering command to use
52	{                   % THESE headers.
53	\section{#1}
54   \markboth{\textsf{www.libtom.org}}{\thesection ~ {#1}}
55	}
56
57\newcommand{\mystarsection}[1]    % Re-define the chaptering command to use
58	{                   % THESE headers.
59	\section*{#1}
60   \markboth{\textsf{www.libtom.org}}{{#1}}
61	}
62\pagestyle{empty}
63\begin{document}
64\frontmatter
65\pagestyle{empty}
66
67~
68
69\vspace{2in}
70
71~
72
73\begin{center}
74\begin{Huge}LibTomCrypt\end{Huge}
75
76~
77
78\begin{large}Developer Manual\end{large}
79
80~
81
82\vspace{15mm}
83
84
85\begin{tabular}{c}
86Tom St Denis \\
87LibTom Projects
88\end{tabular}
89\end{center}
90\vfil
91\newpage
92This document is part of the LibTomCrypt package and is hereby released into the public domain.
93
94~
95
96Open Source.  Open Academia.  Open Minds.
97
98~
99
100\begin{flushright}
101Tom St Denis
102~
103
104Ottawa, Ontario
105~
106
107Canada
108~
109\vfil
110\end{flushright}
111\newpage
112
113\tableofcontents
114\listoffigures
115\pagestyle{myheadings}
116\mainmatter
117\chapter{Introduction}
118\mysection{What is the LibTomCrypt?}
119LibTomCrypt is a portable ISO C cryptographic library meant to be a tool set for cryptographers who are
120designing cryptosystems.  It supports symmetric ciphers, one-way hashes, pseudo-random number generators,
121public key cryptography (via PKCS \#1 RSA, DH or ECCDH), and a plethora of support routines.
122
123The library was designed such that new ciphers/hashes/PRNGs can be added at run-time and the existing API
124(and helper API functions) are able to use the new designs automatically.  There exists self-check functions for each
125block cipher and hash function to ensure that they compile and execute to the published design specifications.  The library
126also performs extensive parameter error checking to prevent any number of run-time exploits or errors.
127
128\subsection{What the library IS for?}
129
130The library serves as a toolkit for developers who have to solve cryptographic problems.  Out of the box LibTomCrypt
131does not process SSL or OpenPGP messages, it doesn't read X.509 certificates, or write PEM encoded data.  It does, however,
132provide all of the tools required to build such functionality.  LibTomCrypt was designed to be a flexible library that
133was not tied to any particular cryptographic problem.
134
135\mysection{Why did I write it?}
136You may be wondering, \textit{Tom, why did you write a crypto library.  I already have one.}  Well the reason falls into
137two categories:
138\begin{enumerate}
139    \item I am too lazy to figure out someone else's API.  I'd rather invent my own simpler API and use that.
140    \item It was (still is) good coding practice.
141\end{enumerate}
142
143The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc.  I'm trying to write my
144{\bf own} crypto library and hopefully along the way others will appreciate the work.
145
146With this library all core functions (ciphers, hashes, prngs, and bignum) have the same prototype definition.  They all load
147and store data in a format independent of the platform.  This means if you encrypt with Blowfish on a PPC it should decrypt
148on an x86 with zero problems.  The consistent API also means that if you learn how to use Blowfish with the library you
149know how to use Safer+, RC6, or Serpent as well.  With all of the core functions there are central descriptor tables
150that can be used to make a program automatically pick between ciphers, hashes and PRNGs at run-time.  That means your
151application can support all ciphers/hashes/prngs/bignum without changing the source code.
152
153Not only did I strive to make a consistent and simple API to work with but I also attempted to make the library
154configurable in terms of its build options.  Out of the box the library will build with any modern version of GCC
155without having to use configure scripts.  This means that the library will work with platforms where development
156tools may be limited (e.g. no autoconf).
157
158On top of making the build simple and the API approachable I've also attempted for a reasonably high level of
159robustness and efficiency.  LibTomCrypt traps and returns a series of errors ranging from invalid
160arguments to buffer overflows/overruns.  It is mostly thread safe and has been clocked on various platforms
161with \textit{cycles per byte} timings that are comparable (and often favourable) to other libraries such as OpenSSL and
162Crypto++.
163
164\subsection{Modular}
165The LibTomCrypt package has also been written to be very modular.  The block ciphers, one--way hashes,
166pseudo--random number generators (PRNG), and bignum math routines are all used within the API through \textit{descriptor} tables which
167are essentially structures with pointers to functions.  While you can still call particular functions
168directly (\textit{e.g. sha256\_process()}) this descriptor interface allows the developer to customize their
169usage of the library.
170
171For example, consider a hardware platform with a specialized RNG device.  Obviously one would like to tap
172that for the PRNG needs within the library (\textit{e.g. making a RSA key}).  All the developer has to do
173is write a descriptor and the few support routines required for the device.  After that the rest of the
174API can make use of it without change.  Similarly imagine a few years down the road when AES2
175(\textit{or whatever they call it}) has been invented.  It can be added to the library and used within applications
176with zero modifications to the end applications provided they are written properly.
177
178This flexibility within the library means it can be used with any combination of primitive algorithms and
179unlike libraries like OpenSSL is not tied to direct routines.  For instance, in OpenSSL there are CBC block
180mode routines for every single cipher.  That means every time you add or remove a cipher from the library
181you have to update the associated support code as well.  In LibTomCrypt the associated code (\textit{chaining modes in this case})
182are not directly tied to the ciphers.  That is a new cipher can be added to the library by simply providing
183the key setup, ECB decrypt and encrypt and test vector routines.  After that all five chaining mode routines
184can make use of the cipher right away.
185
186\mysection{License}
187
188The project is hereby released as public domain.
189
190\mysection{Patent Disclosure}
191
192The author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice.  To the best
193of the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers.
194They can be removed from a build by simply commenting out the two appropriate lines in \textit{tomcrypt\_custom.h}.  The rest
195of the ciphers and hashes are patent free or under patents that have since expired.
196
197The RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations.  This means you can use
198the ciphers you just can't advertise that you are doing so.
199
200\mysection{Thanks}
201I would like to give thanks to the following people (in no particular order) for helping me develop this project from
202early on:
203\begin{enumerate}
204   \item Richard van de Laarschot
205   \item Richard Heathfield
206   \item Ajay K. Agrawal
207   \item Brian Gladman
208   \item Svante Seleborg
209   \item Clay Culver
210   \item Jason Klapste
211   \item Dobes Vandermeer
212   \item Daniel Richards
213   \item Wayne Scott
214   \item Andrew Tyler
215   \item Sky Schulz
216   \item Christopher Imes
217\end{enumerate}
218
219There have been quite a few other people as well.  Please check the change log to see who else has contributed from
220time to time.
221
222\chapter{The Application Programming Interface (API)}
223\mysection{Introduction}
224\index{CRYPT\_ERROR} \index{CRYPT\_OK}
225
226In general the API is very simple to memorize and use.  Most of the functions return either {\bf void} or {\bf int}.  Functions
227that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful, or one of the many error codes
228if it failed.  Certain functions that return int will return $-1$ to indicate an error.  These functions will be explicitly
229commented upon.  When a function does return a CRYPT error code it can be translated into a string with
230
231\index{error\_to\_string()}
232\begin{verbatim}
233const char *error_to_string(int err);
234\end{verbatim}
235
236An example of handling an error is:
237\begin{small}
238\begin{verbatim}
239void somefunc(void)
240{
241   int err;
242
243   /* call a cryptographic function */
244   if ((err = some_crypto_function(...)) != CRYPT_OK) {
245      printf("A crypto error occurred, %s\n", error_to_string(err));
246      /* perform error handling */
247   }
248   /* continue on if no error occurred */
249}
250\end{verbatim}
251\end{small}
252
253There is no initialization routine for the library and for the most part the code is thread safe.  The only thread
254related issue is if you use the same symmetric cipher, hash or public key state data in multiple threads.  Normally
255that is not an issue.
256
257To include the prototypes for \textit{LibTomCrypt.a} into your own program simply include \textit{tomcrypt.h} like so:
258\begin{small}
259\begin{verbatim}
260#include <tomcrypt.h>
261int main(void) {
262    return 0;
263}
264\end{verbatim}
265\end{small}
266
267The header file \textit{tomcrypt.h} also includes \textit{stdio.h}, \textit{string.h}, \textit{stdlib.h}, \textit{time.h} and \textit{ctype.h}.
268
269\mysection{Macros}
270
271There are a few helper macros to make the coding process a bit easier.  The first set are related to loading and storing
27232/64-bit words in little/big endian format.  The macros are:
273
274\index{STORE32L} \index{STORE64L} \index{LOAD32L} \index{LOAD64L} \index{STORE32H} \index{STORE64H} \index{LOAD32H} \index{LOAD64H} \index{BSWAP}
275\newpage
276\begin{figure}[hpbt]
277\begin{small}
278\begin{center}
279\begin{tabular}{|c|c|c|}
280     \hline STORE32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 3]$ \\
281     \hline STORE64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 7]$ \\
282     \hline LOAD32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[0 \ldots 3] \to x$ \\
283     \hline LOAD64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[0 \ldots 7] \to x$ \\
284     \hline STORE32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[3 \ldots 0]$ \\
285     \hline STORE64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[7 \ldots 0]$ \\
286     \hline LOAD32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[3 \ldots 0] \to x$ \\
287     \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\
288     \hline BSWAP(x) & {\bf unsigned long} x & Swap bytes \\
289     \hline
290\end{tabular}
291\caption{Load And Store Macros}
292\end{center}
293\end{small}
294\end{figure}
295
296There are 32 and 64-bit cyclic rotations as well:
297\index{ROL} \index{ROR} \index{ROL64} \index{ROR64} \index{ROLc} \index{RORc} \index{ROL64c} \index{ROR64c}
298\begin{figure}[hpbt]
299\begin{small}
300\begin{center}
301\begin{tabular}{|c|c|c|}
302     \hline ROL(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 31$ \\
303     \hline ROLc(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 31$ \\
304     \hline ROR(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 31$ \\
305     \hline RORc(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 31$ \\
306     \hline && \\
307     \hline ROL64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y, 0 \le y \le 63$ \\
308     \hline ROL64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x << y, 0 \le y \le 63$ \\
309     \hline ROR64(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y, 0 \le y \le 63$ \\
310     \hline ROR64c(x, y) & {\bf unsigned long} x, {\bf const unsigned long} y & $x >> y, 0 \le y \le 63$ \\
311     \hline
312\end{tabular}
313\caption{Rotate Macros}
314\end{center}
315\end{small}
316\end{figure}
317
318\mysection{Functions with Variable Length Output}
319Certain functions such as (for example) \textit{rsa\_export()} give an output that is variable length.  To prevent buffer overflows you
320must pass it the length of the buffer where the output will be stored.  For example:
321\index{rsa\_export()} \index{error\_to\_string()} \index{variable length output}
322\begin{small}
323\begin{verbatim}
324#include <tomcrypt.h>
325int main(void) {
326    rsa_key key;
327    unsigned char buffer[1024];
328    unsigned long x;
329    int err;
330
331    /* ... Make up the RSA key somehow ... */
332
333    /* lets export the key, set x to the size of the
334     * output buffer */
335    x = sizeof(buffer);
336    if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) {
337       printf("Export error: %s\n", error_to_string(err));
338       return -1;
339    }
340
341    /* if rsa_export() was successful then x will have
342     * the size of the output */
343    printf("RSA exported key takes %d bytes\n", x);
344
345    /* ... do something with the buffer */
346
347    return 0;
348}
349\end{verbatim}
350\end{small}
351In the above example if the size of the RSA public key was more than 1024 bytes this function would return an error code
352indicating a buffer overflow would have occurred.  If the function succeeds, it stores the length of the output back into
353\textit{x} so that the calling application will know how many bytes were used.
354
355As of v1.13, most functions will update your length on failure to indicate the size required by the function.  Not all functions
356support this so please check the source before you rely on it doing that.
357
358\mysection{Functions that need a PRNG}
359\index{Pseudo Random Number Generator} \index{PRNG}
360Certain functions such as \textit{rsa\_make\_key()} require a Pseudo Random Number Generator (PRNG).  These functions do not setup
361the PRNG themselves so it is the responsibility of the calling function to initialize the PRNG before calling them.
362
363Certain PRNG algorithms do not require a \textit{prng\_state} argument (sprng for example).  The \textit{prng\_state} argument
364may be passed as \textbf{NULL} in such situations.
365
366\index{register\_prng()} \index{rsa\_make\_key()}
367\begin{small}
368\begin{verbatim}
369#include <tomcrypt.h>
370int main(void) {
371    rsa_key key;
372    int     err;
373
374    /* register the system RNG */
375    register_prng(&sprng_desc)
376
377    /* make a 1024-bit RSA key with the system RNG */
378    if ((err = rsa_make_key(NULL, find_prng("sprng"), 1024/8, 65537, &key))
379        != CRYPT_OK) {
380       printf("make_key error: %s\n", error_to_string(err));
381       return -1;
382    }
383
384    /* use the key ... */
385
386    return 0;
387}
388\end{verbatim}
389\end{small}
390
391\mysection{Functions that use Arrays of Octets}
392Most functions require inputs that are arrays of the data type \textit{unsigned char}.  Whether it is a symmetric key, IV
393for a chaining mode or public key packet it is assumed that regardless of the actual size of \textit{unsigned char} only the
394lower eight bits contain data.  For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine, you
395must pass in (a pointer to) an array of 32 \textit{unsigned char} variables.  Certain routines (such as SAFER+) take
396special care to work properly on platforms where an \textit{unsigned char} is not eight bits.
397
398For the purposes of this library, the term \textit{byte} will refer to an octet or eight bit word.  Typically an array of
399type \textit{byte} will be synonymous with an array of type \textit{unsigned char.}
400
401\chapter{Symmetric Block Ciphers}
402\mysection{Core Functions}
403LibTomCrypt provides several block ciphers with an ECB block mode interface.  It is important to first note that you
404should never use the ECB modes directly to encrypt data.  Instead you should use the ECB functions to make a chaining mode,
405or use one of the provided chaining modes.  All of the ciphers are written as ECB interfaces since it allows the rest of
406the API to grow in a modular fashion.
407
408\subsection{Key Scheduling}
409All ciphers store their scheduled keys in a single data type called \textit{symmetric\_key}.  This allows all ciphers to
410have the same prototype and store their keys as naturally as possible.  This also removes the need for dynamic memory
411allocation, and allows you to allocate a fixed sized buffer for storing scheduled keys.  All ciphers must provide six visible
412functions which are (given that XXX is the name of the cipher) the following:
413\index{Cipher Setup}
414\begin{verbatim}
415int XXX_setup(const unsigned char *key,
416                              int  keylen,
417                              int  rounds,
418                    symmetric_key *skey);
419\end{verbatim}
420
421The XXX\_setup() routine will setup the cipher to be used with a given number of rounds and a given key length (in bytes).
422The number of rounds can be set to zero to use the default, which is generally a good idea.
423
424If the function returns successfully the variable \textit{skey} will have a scheduled key stored in it.  It's important to note
425that you should only used this scheduled key with the intended cipher.  For example, if you call \textit{blowfish\_setup()} do not
426pass the scheduled key onto \textit{rc5\_ecb\_encrypt()}.  All built--in setup functions do not allocate memory off the heap so
427when you are done with a key you can simply discard it (e.g. they can be on the stack).  However, to maintain proper coding
428practices you should always call the respective XXX\_done() function.  This allows for quicker porting to applications with
429externally supplied plugins.
430
431\subsection{ECB Encryption and Decryption}
432To encrypt or decrypt a block in ECB mode there are these two functions per cipher:
433\index{Cipher Encrypt} \index{Cipher Decrypt}
434\begin{verbatim}
435int XXX_ecb_encrypt(const unsigned char *pt,
436                          unsigned char *ct,
437                          symmetric_key *skey);
438
439int XXX_ecb_decrypt(const unsigned char *ct,
440                          unsigned char *pt,
441                          symmetric_key *skey);
442\end{verbatim}
443These two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on
444which cipher you are using.}, storing the result in the \textit{ct} buffer (\textit{pt} resp.).  It is possible that the input and output buffer are
445the same buffer.  For the encrypt function \textit{pt}\footnote{pt stands for plaintext.} is the input and
446\textit{ct}\footnote{ct stands for ciphertext.} is the output.  For the decryption function it's the opposite.  They both
447return \textbf{CRYPT\_OK} on success.  To test a particular cipher against test vectors\footnote{As published in their design papers.}
448call the following self-test function.
449
450\subsection{Self--Testing}
451\index{Cipher Testing}
452\begin{verbatim}
453int XXX_test(void);
454\end{verbatim}
455This function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is
456based upon.
457
458\subsection{Key Sizing}
459For each cipher there is a function which will help find a desired key size.  It is specified as follows:
460\index{Key Sizing}
461\begin{verbatim}
462int XXX_keysize(int *keysize);
463\end{verbatim}
464Essentially, it will round the input keysize in \textit{keysize} down to the next appropriate key size.  This function
465will return {\bf CRYPT\_OK} if the key size specified is acceptable.  For example:
466\begin{small}
467\begin{verbatim}
468#include <tomcrypt.h>
469int main(void)
470{
471   int keysize, err;
472
473   /* now given a 20 byte key what keysize does Twofish want to use? */
474   keysize = 20;
475   if ((err = twofish_keysize(&keysize)) != CRYPT_OK) {
476      printf("Error getting key size: %s\n", error_to_string(err));
477      return -1;
478   }
479   printf("Twofish suggested a key size of %d\n", keysize);
480   return 0;
481}
482\end{verbatim}
483\end{small}
484This should indicate a keysize of sixteen bytes is suggested by storing 16 in \textit{keysize.}
485
486\subsection{Cipher Termination}
487When you are finished with a cipher you can de--initialize it with the done function.
488\begin{verbatim}
489void XXX_done(symmetric_key *skey);
490\end{verbatim}
491For the software based ciphers within LibTomCrypt, these functions will not do anything.  However, user supplied
492cipher descriptors may require to be called for resource management purposes.  To be compliant, all functions which call a cipher
493setup function must also call the respective cipher done function when finished.
494
495\subsection{Simple Encryption Demonstration}
496An example snippet that encodes a block with Blowfish in ECB mode.
497
498\index{blowfish\_setup()} \index{blowfish\_ecb\_encrypt()} \index{blowfish\_ecb\_decrypt()} \index{blowfish\_done()}
499\begin{small}
500\begin{verbatim}
501#include <tomcrypt.h>
502int main(void)
503{
504   unsigned char pt[8], ct[8], key[8];
505   symmetric_key skey;
506   int err;
507
508   /* ... key is loaded appropriately in key ... */
509   /* ... load a block of plaintext in pt ... */
510
511   /* schedule the key */
512   if ((err = blowfish_setup(key, /* the key we will use */
513                               8, /* key is 8 bytes (64-bits) long */
514                               0, /* 0 == use default # of rounds */
515                           &skey) /* where to put the scheduled key */
516       ) != CRYPT_OK) {
517      printf("Setup error: %s\n", error_to_string(err));
518      return -1;
519   }
520
521   /* encrypt the block */
522   blowfish_ecb_encrypt(pt,       /* encrypt this 8-byte array */
523                        ct,       /* store encrypted data here */
524                        &skey);   /* our previously scheduled key */
525
526   /* now ct holds the encrypted version of pt */
527
528   /* decrypt the block */
529   blowfish_ecb_decrypt(ct,       /* decrypt this 8-byte array */
530                        pt,       /* store decrypted data here */
531                        &skey);   /* our previously scheduled key */
532
533   /* now we have decrypted ct to the original plaintext in pt */
534
535   /* Terminate the cipher context */
536   blowfish_done(&skey);
537
538   return 0;
539}
540\end{verbatim}
541\end{small}
542
543\mysection{Key Sizes and Number of Rounds}
544\index{Symmetric Keys}
545As a general rule of thumb, do not use symmetric keys under 80 bits if you can help it.  Only a few of the ciphers support smaller
546keys (mainly for test vectors anyways).  Ideally, your application should be making at least 256 bit keys.  This is not
547because you are to be paranoid.  It is because if your PRNG has a bias of any sort the more bits the better.  For
548example, if you have $\mbox{Pr}\left[X = 1\right] = {1 \over 2} \pm \gamma$ where $\vert \gamma \vert > 0$ then the
549total amount of entropy in N bits is $N \cdot -log_2\left ({1 \over 2} + \vert \gamma \vert \right)$.  So if $\gamma$
550were $0.25$ (a severe bias) a 256-bit string would have about 106 bits of entropy whereas a 128-bit string would have
551only 53 bits of entropy.
552
553The number of rounds of most ciphers is not an option you can change.  Only RC5 allows you to change the number of
554rounds.  By passing zero as the number of rounds all ciphers will use their default number of rounds.  Generally the
555ciphers are configured such that the default number of rounds provide adequate security for the given block and key
556size.
557
558\mysection{The Cipher Descriptors}
559\index{Cipher Descriptor}
560To facilitate automatic routines an array of cipher descriptors is provided in the array \textit{cipher\_descriptor}.  An element
561of this array has the following (partial) format (See Section \ref{sec:cipherdesc}):
562
563\begin{small}
564\begin{verbatim}
565struct _cipher_descriptor {
566   /** name of cipher */
567   char *name;
568
569   /** internal ID */
570   unsigned char ID;
571
572   /** min keysize (octets) */
573   int  min_key_length,
574
575   /** max keysize (octets) */
576        max_key_length,
577
578   /** block size (octets) */
579        block_length,
580
581   /** default number of rounds */
582        default_rounds;
583...<snip>...
584};
585\end{verbatim}
586\end{small}
587
588Where \textit{name} is the lower case ASCII version of the name.  The fields \textit{min\_key\_length} and \textit{max\_key\_length}
589are the minimum and maximum key sizes in bytes.  The \textit{block\_length} member is the block size of the cipher
590in bytes.  As a good rule of thumb it is assumed that the cipher supports
591the min and max key lengths but not always everything in between.  The \textit{default\_rounds} field is the default number
592of rounds that will be used.
593
594For a plugin to be compliant it must provide at least each function listed before the accelerators begin.  Accelerators are optional,
595and if missing will be emulated in software.
596
597The remaining fields are all pointers to the core functions for each cipher.  The end of the cipher\_descriptor array is
598marked when \textit{name} equals {\bf NULL}.
599
600As of this release the current cipher\_descriptors elements are the following:
601\vfil
602\index{Cipher descriptor table}
603\index{blowfish\_desc} \index{xtea\_desc} \index{rc2\_desc} \index{rc5\_desc} \index{rc6\_desc} \index{saferp\_desc} \index{aes\_desc} \index{twofish\_desc}
604\index{des\_desc} \index{des3\_desc} \index{noekeon\_desc} \index{skipjack\_desc} \index{anubis\_desc} \index{khazad\_desc} \index{kseed\_desc} \index{kasumi\_desc}
605\begin{figure}[hpbt]
606\begin{small}
607\begin{center}
608\begin{tabular}{|c|c|c|c|c|c|}
609     \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Block Size} & \textbf{Key Range} & \textbf{Rounds} \\
610     \hline Blowfish & blowfish\_desc & 8 & 8 $\ldots$ 56 & 16 \\
611     \hline X-Tea & xtea\_desc & 8 & 16 & 32 \\
612     \hline RC2 & rc2\_desc & 8 & 8 $\ldots$ 128 & 16 \\
613     \hline RC5-32/12/b & rc5\_desc & 8 & 8 $\ldots$ 128 & 12 $\ldots$ 24 \\
614     \hline RC6-32/20/b & rc6\_desc & 16 & 8 $\ldots$ 128 & 20 \\
615     \hline SAFER+ & saferp\_desc &16 & 16, 24, 32 & 8, 12, 16 \\
616     \hline AES & aes\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\
617                & aes\_enc\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\
618     \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\
619     \hline DES & des\_desc & 8 & 7 & 16 \\
620     \hline 3DES (EDE mode) & des3\_desc & 8 & 21 & 16 \\
621     \hline CAST5 (CAST-128) & cast5\_desc & 8 & 5 $\ldots$ 16 & 12, 16 \\
622     \hline Noekeon & noekeon\_desc & 16 & 16 & 16 \\
623     \hline Skipjack & skipjack\_desc & 8 & 10 & 32 \\
624     \hline Anubis & anubis\_desc & 16 & 16 $\ldots$ 40 & 12 $\ldots$ 18 \\
625     \hline Khazad & khazad\_desc & 8 & 16 & 8 \\
626     \hline SEED   & kseed\_desc & 16 & 16 & 16 \\
627     \hline KASUMI & kasumi\_desc & 8 & 16 & 8 \\
628     \hline
629\end{tabular}
630\end{center}
631\end{small}
632\caption{Built--In Software Ciphers}
633\end{figure}
634
635\subsection{Notes}
636\begin{small}
637\begin{enumerate}
638\item
639For AES, (also known as Rijndael) there are four descriptors which complicate issues a little.  The descriptors
640rijndael\_desc and rijndael\_enc\_desc provide the cipher named \textit{rijndael}.  The descriptors aes\_desc and
641aes\_enc\_desc provide the cipher name \textit{aes}.  Functionally both \textit{rijndael} and \textit{aes} are the same cipher.  The
642only difference is when you call find\_cipher() you have to pass the correct name.  The cipher descriptors with \textit{enc}
643in the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine
644and tables.  The decryption and self--test function pointers of both \textit{encrypt only} descriptors are set to \textbf{NULL} and
645should not be called.
646
647The \textit{encrypt only} descriptors are useful for applications that only use the encryption function of the cipher.  Algorithms such
648as EAX, PMAC and OMAC only require the encryption function.  So far this \textit{encrypt only} functionality has only been implemented for
649Rijndael as it makes the most sense for this cipher.
650
651\item
652Note that for \textit{DES} and \textit{3DES} they use 8 and 24 byte keys but only 7 and 21 [respectively] bytes of the keys are in
653fact 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
654byte string from the real 7/21 byte key.
655
656\item
657Note that \textit{Twofish} has additional configuration options (Figure \ref{fig:twofishopts}) that take place at build time.  These options are found in
658the file \textit{tomcrypt\_cfg.h}.  The first option is \textit{TWOFISH\_SMALL} which when defined will force the Twofish code
659to not pre-compute the Twofish \textit{$g(X)$} function as a set of four $8 \times 32$ s-boxes.  This means that a scheduled
660key will require less ram but the resulting cipher will be slower.  The second option is \textit{TWOFISH\_TABLES} which when
661defined will force the Twofish code to use pre-computed tables for the two s-boxes $q_0, q_1$ as well as the multiplication
662by the polynomials 5B and EF used in the MDS multiplication.  As a result the code is faster and slightly larger.  The
663speed increase is useful when \textit{TWOFISH\_SMALL} is defined since the s-boxes and MDS multiply form the heart of the
664Twofish round function.
665
666\begin{figure}[hpbt]
667\index{Twofish build options} \index{TWOFISH\_SMALL} \index{TWOFISH\_TABLES}
668\begin{small}
669\begin{center}
670\begin{tabular}{|l|l|l|}
671\hline \textbf{TWOFISH\_SMALL} & \textbf{TWOFISH\_TABLES} & \textbf{Speed and Memory (per key)} \\
672\hline undefined & undefined & Very fast, 4.2KB of ram. \\
673\hline undefined & defined & Faster key setup, larger code. \\
674\hline defined & undefined & Very slow, 0.2KB of ram. \\
675\hline defined & defined & Faster, 0.2KB of ram, larger code. \\
676\hline
677\end{tabular}
678\end{center}
679\end{small}
680\caption{Twofish Build Options}
681\label{fig:twofishopts}
682\end{figure}
683\end{enumerate}
684\end{small}
685
686To work with the cipher\_descriptor array there is a function:
687\index{find\_cipher()}
688\begin{verbatim}
689int find_cipher(char *name)
690\end{verbatim}
691Which will search for a given name in the array.  It returns $-1$ if the cipher is not found, otherwise it returns
692the location in the array where the cipher was found.  For example, to indirectly setup Blowfish you can also use:
693\begin{small}
694\index{register\_cipher()} \index{find\_cipher()} \index{error\_to\_string()}
695\begin{verbatim}
696#include <tomcrypt.h>
697int main(void)
698{
699   unsigned char key[8];
700   symmetric_key skey;
701   int err;
702
703   /* you must register a cipher before you use it */
704   if (register_cipher(&blowfish_desc)) == -1) {
705      printf("Unable to register Blowfish cipher.");
706      return -1;
707   }
708
709   /* generic call to function (assuming the key
710    * in key[] was already setup) */
711   if ((err =
712        cipher_descriptor[find_cipher("blowfish")].
713          setup(key, 8, 0, &skey)) != CRYPT_OK) {
714      printf("Error setting up Blowfish: %s\n", error_to_string(err));
715      return -1;
716   }
717
718   /* ... use cipher ... */
719}
720\end{verbatim}
721\end{small}
722
723A good safety would be to check the return value of \textit{find\_cipher()} before accessing the desired function.  In order
724to use a cipher with the descriptor table you must register it first using:
725\index{register\_cipher()}
726\begin{verbatim}
727int register_cipher(const struct _cipher_descriptor *cipher);
728\end{verbatim}
729Which accepts a pointer to a descriptor and returns the index into the global descriptor table.  If an error occurs such
730as 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
731than once it will just return the index of the first copy.  To remove a cipher call:
732\index{unregister\_cipher()}
733\begin{verbatim}
734int unregister_cipher(const struct _cipher_descriptor *cipher);
735\end{verbatim}
736Which returns {\bf CRYPT\_OK} if it removes the cipher, otherwise it returns {\bf CRYPT\_ERROR}.
737\begin{small}
738\begin{verbatim}
739#include <tomcrypt.h>
740int main(void)
741{
742   int err;
743
744   /* register the cipher */
745   if (register_cipher(&rijndael_desc) == -1) {
746      printf("Error registering Rijndael\n");
747      return -1;
748   }
749
750   /* use Rijndael */
751
752   /* remove it */
753   if ((err = unregister_cipher(&rijndael_desc)) != CRYPT_OK) {
754      printf("Error removing Rijndael: %s\n", error_to_string(err));
755      return -1;
756   }
757
758   return 0;
759}
760\end{verbatim}
761\end{small}
762This snippet is a small program that registers Rijndael.
763
764\mysection{Symmetric Modes of Operations}
765\subsection{Background}
766A typical symmetric block cipher can be used in chaining modes to effectively encrypt messages larger than the block
767size of the cipher.  Given a key $k$, a plaintext $P$ and a cipher $E$ we shall denote the encryption of the block
768$P$ under the key $k$ as $E_k(P)$.  In some modes there exists an initial vector denoted as $C_{-1}$.
769
770\subsubsection{ECB Mode}
771\index{ECB mode}
772ECB or Electronic Codebook Mode is the simplest method to use.  It is given as:
773\begin{equation}
774C_i = E_k(P_i)
775\end{equation}
776This mode is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more
777than once.
778
779\subsubsection{CBC Mode}
780\index{CBC mode}
781CBC or Cipher Block Chaining mode is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers.
782It is given as:
783\begin{equation}
784C_i = E_k(P_i \oplus C_{i - 1})
785\end{equation}
786It is important that the initial vector be unique and preferably random for each message encrypted under the same key.
787
788\subsubsection{CTR Mode}
789\index{CTR mode}
790CTR or Counter Mode is a mode which only uses the encryption function of the cipher.  Given a initial vector which is
791treated as a large binary counter the CTR mode is given as:
792\begin{eqnarray}
793C_{-1} = C_{-1} + 1\mbox{ }(\mbox{mod }2^W) \nonumber \\
794C_i = P_i \oplus E_k(C_{-1})
795\end{eqnarray}
796Where $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
797encrypted under the same key replay and swap attacks are infeasible.  CTR mode may look simple but it is as secure
798as the block cipher is under a chosen plaintext attack (provided the initial vector is unique).
799
800\subsubsection{CFB Mode}
801\index{CFB mode}
802CFB or Ciphertext Feedback Mode is a mode akin to CBC.  It is given as:
803\begin{eqnarray}
804C_i = P_i \oplus C_{-1} \nonumber \\
805C_{-1} = E_k(C_i)
806\end{eqnarray}
807Note that in this library the output feedback width is equal to the size of the block cipher.  That is this mode is used
808to encrypt whole blocks at a time.  However, the library will buffer data allowing the user to encrypt or decrypt partial
809blocks without a delay.  When this mode is first setup it will initially encrypt the initial vector as required.
810
811\subsubsection{OFB Mode}
812\index{OFB mode}
813OFB or Output Feedback Mode is a mode akin to CBC as well.  It is given as:
814\begin{eqnarray}
815C_{-1} = E_k(C_{-1}) \nonumber \\
816C_i = P_i \oplus C_{-1}
817\end{eqnarray}
818Like the CFB mode the output width in CFB mode is the same as the width of the block cipher.  OFB mode will also
819buffer the output which will allow you to encrypt or decrypt partial blocks without delay.
820
821\subsection{Choice of Mode}
822My personal preference is for the CTR mode since it has several key benefits:
823\begin{enumerate}
824   \item No short cycles which is possible in the OFB and CFB modes.
825   \item Provably as secure as the block cipher being used under a chosen plaintext attack.
826   \item Technically does not require the decryption routine of the cipher.
827   \item Allows random access to the plaintext.
828   \item Allows the encryption of block sizes that are not equal to the size of the block cipher.
829\end{enumerate}
830The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size.  They
831accomplish this by buffering the data required to complete a block.  This allows you to encrypt or decrypt any size
832block of memory with either of the three modes.
833
834The ECB and CBC modes process blocks of the same size as the cipher at a time.  Therefore, they are less flexible than the
835other modes.
836
837\subsection{Ciphertext Stealing}
838\index{Ciphertext stealing}
839Ciphertext stealing is a method of dealing with messages in CBC mode which are not a multiple of the block length.  This is accomplished
840by encrypting the last ciphertext block in ECB mode, and XOR'ing the output against the last partial block of plaintext.  LibTomCrypt does not
841support this mode directly but it is fairly easy to emulate with a call to the cipher's ecb\_encrypt() callback function.
842
843The more sane way to deal with partial blocks is to pad them with zeroes, and then use CBC normally.
844
845\subsection{Initialization}
846\index{CBC Mode} \index{CTR Mode}
847\index{OFB Mode} \index{CFB Mode}
848The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages.  Assuming the mode
849you want is XXX there is a structure called \textit{symmetric\_XXX} that will contain the information required to
850use that mode.  They have identical setup routines (except CTR and ECB mode):
851\index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()}
852\begin{verbatim}
853int XXX_start(                int  cipher,
854              const unsigned char *IV,
855              const unsigned char *key,
856                              int  keylen,
857                              int  num_rounds,
858                    symmetric_XXX *XXX);
859
860int ctr_start(                int  cipher,
861              const unsigned char *IV,
862              const unsigned char *key,
863                              int  keylen,
864                              int  num_rounds,
865                              int  ctr_mode,
866                    symmetric_CTR *ctr);
867
868int ecb_start(                int  cipher,
869              const unsigned char *key,
870                              int  keylen,
871                              int  num_rounds,
872                    symmetric_ECB *ecb);
873\end{verbatim}
874
875In each case, \textit{cipher} is the index into the cipher\_descriptor array of the cipher you want to use.  The \textit{IV} value is
876the initialization vector to be used with the cipher.  You must fill the IV yourself and it is assumed they are the same
877length as the block size\footnote{In other words the size of a block of plaintext for the cipher, e.g. 8 for DES, 16 for AES, etc.}
878of the cipher you choose.  It is important that the IV  be random for each unique message you want to encrypt.  The
879parameters \textit{key}, \textit{keylen} and \textit{num\_rounds} are the same as in the XXX\_setup() function call.  The final parameter
880is a pointer to the structure you want to hold the information for the mode of operation.
881
882
883In the case of CTR mode there is an additional parameter \textit{ctr\_mode} which specifies the mode that the counter is to be used in.
884If \textbf{CTR\_COUNTER\_ LITTLE\_ENDIAN} was specified then the counter will be treated as a little endian value.  Otherwise, if
885\textbf{CTR\_COUNTER\_BIG\_ENDIAN} was specified the counter will be treated as a big endian value.  As of v1.15 the RFC 3686 style of
886increment then encrypt is also supported.  By OR'ing \textbf{LTC\_CTR\_RFC3686} with the CTR \textit{mode} value, ctr\_start() will increment
887the counter before encrypting it for the first time.
888
889The routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise, they return an error code.
890
891\subsection{Encryption and Decryption}
892To actually encrypt or decrypt the following routines are provided:
893\index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()}
894\index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()}
895\begin{verbatim}
896int XXX_encrypt(const unsigned char *pt,
897                      unsigned char *ct,
898                      unsigned long  len,
899                      symmetric_YYY *YYY);
900
901int XXX_decrypt(const unsigned char *ct,
902                      unsigned char *pt,
903                      unsigned long  len,
904                      symmetric_YYY *YYY);
905\end{verbatim}
906Where \textit{XXX} is one of $\lbrace ecb, cbc, ctr, cfb, ofb \rbrace$.
907
908In all cases, \textit{len} is the size of the buffer (as number of octets) to encrypt or decrypt.  The CTR, OFB and CFB modes are order sensitive but not
909chunk sensitive.  That is you can encrypt \textit{ABCDEF} in three calls like \textit{AB}, \textit{CD}, \textit{EF} or two like \textit{ABCDE} and \textit{F}
910and end up with the same ciphertext.  However, encrypting \textit{ABC} and \textit{DABC} will result in different ciphertexts.  All
911five of the modes will return {\bf CRYPT\_OK} on success from the encrypt or decrypt functions.
912
913In the ECB and CBC cases, \textit{len} must be a multiple of the ciphers block size.  In the CBC case, you must manually pad the end of your message (either with
914zeroes or with whatever your protocol requires).
915
916To decrypt in either mode, 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.
917
918\subsection{IV Manipulation}
919To change or read the IV of a previously initialized chaining mode use the following two functions.
920\index{cbc\_setiv()} \index{cbc\_getiv()} \index{ofb\_setiv()} \index{ofb\_getiv()} \index{cfb\_setiv()} \index{cfb\_getiv()}
921\index{ctr\_setiv()} \index{ctr\_getiv()}
922\begin{verbatim}
923int XXX_getiv(unsigned char *IV,
924              unsigned long *len,
925              symmetric_XXX *XXX);
926
927int XXX_setiv(const unsigned char *IV,
928                    unsigned long  len,
929                    symmetric_XXX *XXX);
930\end{verbatim}
931
932The XXX\_getiv() functions will read the IV out of the chaining mode and store it into \textit{IV} along with the length of the IV
933stored in \textit{len}.  The XXX\_setiv will initialize the chaining mode state as if the original IV were the new IV specified.  The length
934of the IV passed in must be the size of the ciphers block size.
935
936The XXX\_setiv() functions are handy if you wish to change the IV without re--keying the cipher.
937
938What the \textit{setiv} function will do depends on the mode being changed.  In CBC mode, the new IV replaces the existing IV as if it
939were the last ciphertext block.  In CFB mode, the IV is encrypted as if it were the prior encrypted pad.  In CTR mode, the IV is encrypted without
940first incrementing it (regardless of the LTC\_RFC\_3686 flag presence).  In F8 mode, the IV is encrypted and becomes the new pad.  It does not change
941the salted IV, and is only meant to allow seeking within a session.  In LRW, it changes the tweak, forcing a computation of the tweak pad, allowing for
942seeking within the session.  In OFB mode, the IV is encrypted and becomes the new pad.
943
944\subsection{Stream Termination}
945To terminate an open stream call the done function.
946
947\index{ecb\_done()} \index{cbc\_done()}\index{cfb\_done()}\index{ofb\_done()} \index{ctr\_done()}
948\begin{verbatim}
949int XXX_done(symmetric_XXX *XXX);
950\end{verbatim}
951
952This will terminate the stream (by terminating the cipher) and return \textbf{CRYPT\_OK} if successful.
953
954\newpage
955\subsection{Examples}
956\begin{small}
957\begin{verbatim}
958#include <tomcrypt.h>
959int main(void)
960{
961   unsigned char key[16], IV[16], buffer[512];
962   symmetric_CTR ctr;
963   int x, err;
964
965   /* register twofish first */
966   if (register_cipher(&twofish_desc) == -1) {
967      printf("Error registering cipher.\n");
968      return -1;
969   }
970
971   /* somehow fill out key and IV */
972
973   /* start up CTR mode */
974   if ((err = ctr_start(
975        find_cipher("twofish"), /* index of desired cipher */
976                            IV, /* the initial vector */
977                           key, /* the secret key */
978                            16, /* length of secret key (16 bytes) */
979                             0, /* 0 == default # of rounds */
980     CTR_COUNTER_LITTLE_ENDIAN, /* Little endian counter */
981                         &ctr)  /* where to store the CTR state */
982      ) != CRYPT_OK) {
983      printf("ctr_start error: %s\n", error_to_string(err));
984      return -1;
985   }
986
987   /* somehow fill buffer than encrypt it */
988   if ((err = ctr_encrypt(        buffer, /* plaintext */
989                                  buffer, /* ciphertext */
990                          sizeof(buffer), /* length of plaintext pt */
991                                   &ctr)  /* CTR state */
992      ) != CRYPT_OK) {
993      printf("ctr_encrypt error: %s\n", error_to_string(err));
994      return -1;
995   }
996
997   /* make use of ciphertext... */
998
999   /* now we want to decrypt so let's use ctr_setiv */
1000   if ((err = ctr_setiv(  IV, /* the initial IV we gave to ctr_start */
1001                          16, /* the IV is 16 bytes long */
1002                        &ctr) /* the ctr state we wish to modify */
1003       ) != CRYPT_OK) {
1004      printf("ctr_setiv error: %s\n", error_to_string(err));
1005      return -1;
1006   }
1007
1008   if ((err = ctr_decrypt(        buffer, /* ciphertext */
1009                                  buffer, /* plaintext */
1010                          sizeof(buffer), /* length of plaintext */
1011                                   &ctr)  /* CTR state */
1012      ) != CRYPT_OK) {
1013      printf("ctr_decrypt error: %s\n", error_to_string(err));
1014      return -1;
1015   }
1016
1017   /* terminate the stream */
1018   if ((err = ctr_done(&ctr)) != CRYPT_OK) {
1019      printf("ctr_done error: %s\n", error_to_string(err));
1020      return -1;
1021   }
1022
1023   /* clear up and return */
1024   zeromem(key, sizeof(key));
1025   zeromem(&ctr, sizeof(ctr));
1026
1027   return 0;
1028}
1029\end{verbatim}
1030\end{small}
1031
1032\subsection{LRW Mode}
1033LRW mode is a cipher mode which is meant for indexed encryption like used to handle storage media.  It is meant to have efficient seeking and overcome the
1034security problems of ECB mode while not increasing the storage requirements.  It is used much like any other chaining mode except with two key differences.
1035
1036The key is specified as two strings the first key $K_1$ is the (normally AES) key and can be any length (typically 16, 24 or 32 octets long).  The second key
1037$K_2$ is the \textit{tweak} key and is always 16 octets long.  The tweak value is \textbf{NOT} a nonce or IV value it must be random and secret.
1038
1039To initialize LRW mode use:
1040
1041\index{lrw\_start()}
1042\begin{verbatim}
1043int lrw_start(                int  cipher,
1044              const unsigned char *IV,
1045              const unsigned char *key,
1046                              int  keylen,
1047              const unsigned char *tweak,
1048                              int  num_rounds,
1049                    symmetric_LRW *lrw);
1050\end{verbatim}
1051
1052This will initialize the LRW context with the given (16 octet) \textit{IV}, cipher $K_1$ \textit{key} of length \textit{keylen} octets and the (16 octet) $K_2$ \textit{tweak}.
1053While LRW was specified to be used only with AES, LibTomCrypt will allow any 128--bit block cipher to be specified as indexed by \textit{cipher}.  The
1054number of rounds for the block cipher \textit{num\_rounds} can be 0 to use the default number of rounds for the given cipher.
1055
1056To process data use the following functions:
1057
1058\index{lrw\_encrypt()} \index{lrw\_decrypt()}
1059\begin{verbatim}
1060int lrw_encrypt(const unsigned char *pt,
1061                      unsigned char *ct,
1062                      unsigned long  len,
1063                      symmetric_LRW *lrw);
1064
1065int lrw_decrypt(const unsigned char *ct,
1066                      unsigned char *pt,
1067                      unsigned long  len,
1068                      symmetric_LRW *lrw);
1069\end{verbatim}
1070
1071These will encrypt (or decrypt) the plaintext to the ciphertext buffer (or vice versa).  The length is specified by \textit{len} in octets but must be a multiple
1072of 16.  The LRW code uses a fast tweak update such that consecutive blocks are encrypted faster than if random seeking where used.
1073
1074To manipulate the IV use the following functions:
1075
1076\index{lrw\_getiv()} \index{lrw\_setiv()}
1077\begin{verbatim}
1078int lrw_getiv(unsigned char *IV,
1079              unsigned long *len,
1080              symmetric_LRW *lrw);
1081
1082int lrw_setiv(const unsigned char *IV,
1083                    unsigned long  len,
1084                    symmetric_LRW *lrw);
1085\end{verbatim}
1086These will get or set the 16--octet IV.  Note that setting the IV is the same as \textit{seeking} and unlike other modes is not a free operation.  It requires
1087updating the entire tweak which is slower than sequential use.  Avoid seeking excessively in performance constrained code.
1088
1089To terminate the LRW state use the following:
1090
1091\index{lrw\_done()}
1092\begin{verbatim}
1093int lrw_done(symmetric_LRW *lrw);
1094\end{verbatim}
1095
1096\subsection{F8 Mode}
1097\index{F8 Mode}
1098The F8 Chaining mode (see RFC 3711 for instance) is yet another chaining mode for block ciphers.  It behaves much like CTR mode in that it XORs a keystream
1099against the plaintext to encrypt.  F8 mode comes with the additional twist that the counter value is secret, encrypted by a \textit{salt key}.  We
1100initialize F8 mode with the following function call:
1101
1102\index{f8\_start()}
1103\begin{verbatim}
1104int f8_start(                int  cipher,
1105             const unsigned char *IV,
1106             const unsigned char *key,
1107                             int  keylen,
1108             const unsigned char *salt_key,
1109                             int  skeylen,
1110                             int  num_rounds,
1111                    symmetric_F8 *f8);
1112\end{verbatim}
1113This will start the F8 mode state using \textit{key} as the secret key, \textit{IV} as the counter.  It uses the \textit{salt\_key} as IV encryption key
1114(\textit{m} in the RFC 3711).  The salt\_key can be shorter than the secret key but it should not be longer.
1115
1116To encrypt or decrypt data we use the following two functions:
1117
1118\index{f8\_encrypt()} \index{f8\_decrypt()}
1119\begin{verbatim}
1120int f8_encrypt(const unsigned char *pt,
1121                     unsigned char *ct,
1122                     unsigned long  len,
1123                      symmetric_F8 *f8);
1124
1125int f8_decrypt(const unsigned char *ct,
1126                     unsigned char *pt,
1127                     unsigned long  len,
1128                      symmetric_F8 *f8);
1129\end{verbatim}
1130These will encrypt or decrypt a variable length array of bytes using the F8 mode state specified.  The length is specified in bytes and does not have to be a multiple
1131of the ciphers block size.
1132
1133To change or retrieve the current counter IV value use the following functions:
1134\index{f8\_getiv()} \index{f8\_setiv()}
1135\begin{verbatim}
1136int f8_getiv(unsigned char *IV,
1137             unsigned long *len,
1138              symmetric_F8 *f8);
1139
1140int f8_setiv(const unsigned char *IV,
1141                   unsigned long  len,
1142                    symmetric_F8 *f8);
1143\end{verbatim}
1144These work with the current IV value only and not the encrypted IV value specified during the call to f8\_start().  The purpose of these two functions is to be
1145able to seek within a current session only.  If you want to change the session IV you will have to call f8\_done() and then start a new state with
1146f8\_start().
1147
1148To terminate an F8 state call the following function:
1149
1150\index{f8\_done()}
1151\begin{verbatim}
1152int f8_done(symmetric_F8 *f8);
1153\end{verbatim}
1154
1155\vfil
1156\mysection{Encrypt and Authenticate Modes}
1157
1158\subsection{EAX Mode}
1159LibTomCrypt provides support for a mode called EAX\footnote{See
1160M. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the way it was intended to be used
1161by the designers.  First, a short description of what EAX mode is before we explain how to use it.  EAX is a mode that requires a cipher,
1162CTR and OMAC support and provides encryption and
1163authentication\footnote{Note that since EAX only requires OMAC and CTR you may use \textit{encrypt only} cipher descriptors with this mode.}.
1164It is initialized with a random \textit{nonce} that can be shared publicly, a \textit{header} which can be fixed and public, and a random secret symmetric key.
1165
1166The \textit{header} data is meant to be meta--data associated with a stream that isn't private (e.g., protocol messages).  It can
1167be 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 changes in the output tag.
1168
1169The mode can then process plaintext producing ciphertext as well as compute a partial checksum.  The actual checksum
1170called a \textit{tag} is only emitted when the message is finished.  In the interim, the user can process any arbitrary
1171sized message block to send to the recipient as ciphertext.  This makes the EAX mode especially suited for streaming modes
1172of operation.
1173
1174The mode is initialized with the following function.
1175\index{eax\_init()}
1176\begin{verbatim}
1177int eax_init(          eax_state *eax,
1178                             int  cipher,
1179             const unsigned char *key,
1180                   unsigned long  keylen,
1181             const unsigned char *nonce,
1182                   unsigned long  noncelen,
1183             const unsigned char *header,
1184                   unsigned long  headerlen);
1185\end{verbatim}
1186
1187Where \textit{eax} is the EAX state.  The \textit{cipher} parameter is the index of the desired cipher in the descriptor table.
1188The \textit{key} parameter is the shared secret symmetric key of length \textit{keylen} octets.  The \textit{nonce} parameter is the
1189random public string of length \textit{noncelen} octets.  The \textit{header} parameter is the random (or fixed or \textbf{NULL}) header for the
1190message of length \textit{headerlen} octets.
1191
1192When this function completes, the \textit{eax} state will be initialized such that you can now either have data decrypted or
1193encrypted in EAX mode.  Note: if \textit{headerlen} is zero you may pass \textit{header} as \textbf{NULL} to indicate there is no initial header data.
1194
1195To encrypt or decrypt data in a streaming mode use the following.
1196\index{eax\_encrypt()} \index{eax\_decrypt()}
1197\begin{verbatim}
1198int eax_encrypt(          eax_state *eax,
1199                const unsigned char *pt,
1200                      unsigned char *ct,
1201                      unsigned long  length);
1202
1203int eax_decrypt(          eax_state *eax,
1204                const unsigned char *ct,
1205                      unsigned char *pt,
1206                      unsigned long  length);
1207\end{verbatim}
1208The function \textit{eax\_encrypt} will encrypt the bytes in \textit{pt} of \textit{length} octets, and store the ciphertext in
1209\textit{ct}.  Note: \textit{ct} and \textit{pt} may be the same region in memory.   This function will also send the ciphertext
1210through the OMAC function.  The function \textit{eax\_decrypt} decrypts \textit{ct}, and stores it in \textit{pt}.  This also allows
1211\textit{pt} and \textit{ct} to be the same region in memory.
1212
1213You cannot both encrypt or decrypt with the same \textit{eax} context.  For bi--directional communication you will need to initialize
1214two EAX contexts (preferably with different headers and nonces).
1215
1216Note: both of these functions allow you to send the data in any granularity but the order is important.  While
1217the eax\_init() function allows you to add initial header data to the stream you can also add header data during the
1218EAX stream with the following.
1219
1220\index{eax\_addheader()}
1221\begin{verbatim}
1222int eax_addheader(          eax_state *eax,
1223                  const unsigned char *header,
1224                        unsigned long  length);
1225\end{verbatim}
1226This will add the \textit{length} octet from \textit{header} to the given \textit{eax} header.  Once the message is finished, the
1227\textit{tag} (checksum) may be computed with the following function:
1228
1229\index{eax\_done()}
1230\begin{verbatim}
1231int eax_done(    eax_state *eax,
1232             unsigned char *tag,
1233             unsigned long *taglen);
1234\end{verbatim}
1235This will terminate the EAX state \textit{eax}, and store up to \textit{taglen} bytes of the message tag in \textit{tag}.  The function
1236then stores how many bytes of the tag were written out back in to \textit{taglen}.
1237
1238The EAX mode code can be tested to ensure it matches the test vectors by calling the following function:
1239\index{eax\_test()}
1240\begin{verbatim}
1241int eax_test(void);
1242\end{verbatim}
1243This requires that the AES (or Rijndael) block cipher be registered with the cipher\_descriptor table first.
1244
1245\begin{verbatim}
1246#include <tomcrypt.h>
1247int main(void)
1248{
1249   int           err;
1250   eax_state     eax;
1251   unsigned char pt[64], ct[64], nonce[16], key[16], tag[16];
1252   unsigned long taglen;
1253
1254   if (register_cipher(&rijndael_desc) == -1) {
1255      printf("Error registering Rijndael");
1256      return EXIT_FAILURE;
1257   }
1258
1259   /* ... make up random nonce and key ... */
1260
1261   /* initialize context */
1262   if ((err = eax_init(            &eax,  /* context */
1263                find_cipher("rijndael"),  /* cipher id */
1264                                  nonce,  /* the nonce */
1265                                     16,  /* nonce is 16 bytes */
1266                              "TestApp",  /* example header */
1267                                      7)  /* header length */
1268       ) != CRYPT_OK) {
1269      printf("Error eax_init: %s", error_to_string(err));
1270      return EXIT_FAILURE;
1271   }
1272
1273   /* now encrypt data, say in a loop or whatever */
1274   if ((err = eax_encrypt(     &eax, /* eax context */
1275                                 pt, /* plaintext  (source) */
1276                                 ct, /* ciphertext (destination) */
1277                          sizeof(pt) /* size of plaintext */
1278      ) != CRYPT_OK) {
1279      printf("Error eax_encrypt: %s", error_to_string(err));
1280      return EXIT_FAILURE;
1281   }
1282
1283   /* finish message and get authentication tag */
1284   taglen = sizeof(tag);
1285   if ((err = eax_done(   &eax,      /* eax context */
1286                           tag,      /* where to put tag */
1287                       &taglen       /* length of tag space */
1288      ) != CRYPT_OK) {
1289      printf("Error eax_done: %s", error_to_string(err));
1290      return EXIT_FAILURE;
1291   }
1292
1293   /* now we have the authentication tag in "tag" and
1294    * it's taglen bytes long */
1295}
1296\end{verbatim}
1297
1298You can also perform an entire EAX state on a block of memory in a single function call with the
1299following functions.
1300
1301
1302\index{eax\_encrypt\_authenticate\_memory} \index{eax\_decrypt\_verify\_memory}
1303\begin{verbatim}
1304int eax_encrypt_authenticate_memory(
1305                    int  cipher,
1306    const unsigned char *key,    unsigned long keylen,
1307    const unsigned char *nonce,  unsigned long noncelen,
1308    const unsigned char *header, unsigned long headerlen,
1309    const unsigned char *pt,     unsigned long ptlen,
1310          unsigned char *ct,
1311          unsigned char *tag,    unsigned long *taglen);
1312
1313int eax_decrypt_verify_memory(
1314                    int  cipher,
1315    const unsigned char *key,    unsigned long keylen,
1316    const unsigned char *nonce,  unsigned long noncelen,
1317    const unsigned char *header, unsigned long headerlen,
1318    const unsigned char *ct,     unsigned long ctlen,
1319          unsigned char *pt,
1320          unsigned char *tag,    unsigned long taglen,
1321          int           *res);
1322\end{verbatim}
1323
1324Both essentially just call eax\_init() followed by eax\_encrypt() (or eax\_decrypt() respectively) and eax\_done().  The parameters
1325have the same meaning as with those respective functions.
1326
1327The only difference is eax\_decrypt\_verify\_memory() does not emit a tag.  Instead you pass it a tag as input and it compares it against
1328the tag it computed while decrypting the message.  If the tags match then it stores a $1$ in \textit{res}, otherwise it stores a $0$.
1329
1330\subsection{OCB Mode}
1331LibTomCrypt provides support for a mode called OCB\footnote{See
1332P. Rogaway, M. Bellare, J. Black, T. Krovetz, \textit{OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption}.}
1333.  OCB is an encryption protocol that simultaneously provides authentication.  It is slightly faster to use than EAX mode
1334but is less flexible.  Let's review how to initialize an OCB context.
1335
1336\index{ocb\_init()}
1337\begin{verbatim}
1338int ocb_init(          ocb_state *ocb,
1339                             int  cipher,
1340             const unsigned char *key,
1341                   unsigned long  keylen,
1342             const unsigned char *nonce);
1343\end{verbatim}
1344
1345This will initialize the \textit{ocb} context using cipher descriptor \textit{cipher}.  It will use a \textit{key} of length \textit{keylen}
1346and the random \textit{nonce}.  Note that \textit{nonce} must be a random (public) string the same length as the block ciphers
1347block size (e.g. 16 bytes for AES).
1348
1349This mode has no \textit{Associated Data} like EAX mode does which means you cannot authenticate metadata along with the stream.
1350To encrypt or decrypt data use the following.
1351
1352\index{ocb\_encrypt()} \index{ocb\_decrypt()}
1353\begin{verbatim}
1354int ocb_encrypt(          ocb_state *ocb,
1355                const unsigned char *pt,
1356                      unsigned char *ct);
1357
1358int ocb_decrypt(          ocb_state *ocb,
1359                const unsigned char *ct,
1360                      unsigned char *pt);
1361\end{verbatim}
1362
1363This will encrypt (or decrypt for the latter) a fixed length of data from \textit{pt} to \textit{ct} (vice versa for the latter).
1364They assume that \textit{pt} and \textit{ct} are the same size as the block cipher's block size.  Note that you cannot call
1365both functions given a single \textit{ocb} state.  For bi-directional communication you will have to initialize two \textit{ocb}
1366states (with different nonces).  Also \textit{pt} and \textit{ct} may point to the same location in memory.
1367
1368\subsubsection{State Termination}
1369
1370When you are finished encrypting the message you call the following function to compute the tag.
1371
1372\index{ocb\_done\_encrypt()}
1373\begin{verbatim}
1374int ocb_done_encrypt(          ocb_state *ocb,
1375                     const unsigned char *pt,
1376                           unsigned long  ptlen,
1377                           unsigned char *ct,
1378                           unsigned char *tag,
1379                           unsigned long *taglen);
1380\end{verbatim}
1381
1382This will terminate an encrypt stream \textit{ocb}.  If you have trailing bytes of plaintext that will not complete a block
1383you can pass them here.  This will also encrypt the \textit{ptlen} bytes in \textit{pt} and store them in \textit{ct}.  It will also
1384store up to \textit{taglen} bytes of the tag into \textit{tag}.
1385
1386Note that \textit{ptlen} must be less than or equal to the block size of block cipher chosen.  Also note that if you have
1387an input message equal to the length of the block size then you pass the data here (not to ocb\_encrypt()) only.
1388
1389To terminate a decrypt stream and compared the tag you call the following.
1390
1391\index{ocb\_done\_decrypt()}
1392\begin{verbatim}
1393int ocb_done_decrypt(          ocb_state *ocb,
1394                     const unsigned char *ct,
1395                           unsigned long  ctlen,
1396                           unsigned char *pt,
1397                     const unsigned char *tag,
1398                           unsigned long  taglen,
1399                                     int *res);
1400\end{verbatim}
1401Similarly to the previous function you can pass trailing message bytes into this function.  This will compute the
1402tag of the message (internally) and then compare it against the \textit{taglen} bytes of \textit{tag} provided.  By default
1403\textit{res} is set to zero.  If all \textit{taglen} bytes of \textit{tag} can be verified then \textit{res} is set to one (authenticated
1404message).
1405
1406\subsubsection{Packet Functions}
1407To make life simpler the following two functions are provided for memory bound OCB.
1408
1409%\index{ocb\_encrypt\_authenticate\_memory()}
1410\begin{verbatim}
1411int ocb_encrypt_authenticate_memory(
1412                    int  cipher,
1413    const unsigned char *key,    unsigned long keylen,
1414    const unsigned char *nonce,
1415    const unsigned char *pt,     unsigned long ptlen,
1416          unsigned char *ct,
1417          unsigned char *tag,    unsigned long *taglen);
1418\end{verbatim}
1419
1420This will OCB encrypt the message \textit{pt} of length \textit{ptlen}, and store the ciphertext in \textit{ct}.  The length \textit{ptlen}
1421can be any arbitrary length.
1422
1423\index{ocb\_decrypt\_verify\_memory()}
1424\begin{verbatim}
1425int ocb_decrypt_verify_memory(
1426                    int  cipher,
1427    const unsigned char *key,    unsigned long keylen,
1428    const unsigned char *nonce,
1429    const unsigned char *ct,     unsigned long ctlen,
1430          unsigned char *pt,
1431    const unsigned char *tag,    unsigned long taglen,
1432          int           *res);
1433\end{verbatim}
1434
1435Similarly, this will OCB decrypt, and compare the internally computed tag against the tag provided. \textit{res} is set
1436appropriately.
1437
1438\subsection{CCM Mode}
1439CCM is a NIST proposal for encrypt + authenticate that is centered around using AES (or any 16--byte cipher) as a primitive.  Unlike EAX and OCB mode,
1440it is only meant for \textit{packet} mode where the length of the input is known in advance.  Since it is a packet mode function, CCM only has one
1441function that performs the protocol.
1442
1443\index{ccm\_memory()}
1444\begin{verbatim}
1445int ccm_memory(
1446                    int  cipher,
1447    const unsigned char *key,    unsigned long keylen,
1448    symmetric_key       *uskey,
1449    const unsigned char *nonce,  unsigned long noncelen,
1450    const unsigned char *header, unsigned long headerlen,
1451          unsigned char *pt,     unsigned long ptlen,
1452          unsigned char *ct,
1453          unsigned char *tag,    unsigned long *taglen,
1454                    int  direction);
1455\end{verbatim}
1456
1457This performs the \textit{CCM} operation on the data.  The \textit{cipher} variable indicates which cipher in the descriptor table to use.  It must have a
145816--byte block size for CCM.
1459
1460The key can be specified in one of two fashions.  First, it can be passed as an array of octets in \textit{key} of length \textit{keylen}.  Alternatively,
1461it can be passed in as a previously scheduled key in \textit{uskey}.  The latter fashion saves time when the same key is used for multiple packets.  If
1462\textit{uskey} is not \textbf{NULL}, then \textit{key} may be \textbf{NULL} (and vice-versa).
1463
1464The nonce or salt is \textit{nonce} of length \textit{noncelen} octets.  The header is meta--data you want to send with the message but not have
1465encrypted, it is stored in \textit{header} of length \textit{headerlen} octets.  The header can be zero octets long (if $headerlen = 0$ then
1466you can pass \textit{header} as \textbf{NULL}).
1467
1468The plaintext is stored in \textit{pt}, and the ciphertext in \textit{ct}.  The length of both are expected to be equal and is passed in as \textit{ptlen}.  It is
1469allowable that $pt = ct$.  The \textit{direction} variable indicates whether encryption (direction $=$ \textbf{CCM\_ENCRYPT}) or
1470decryption (direction $=$ \textbf{CCM\_DECRYPT}) is to be performed.
1471
1472As implemented, this version of CCM cannot handle header or plaintext data longer than $2^{32} - 1$ octets long.
1473
1474You can test the implementation of CCM with the following function.
1475
1476\index{ccm\_test()}
1477\begin{verbatim}
1478int ccm_test(void);
1479\end{verbatim}
1480
1481This will return \textbf{CRYPT\_OK} if the CCM routine passes known test vectors.  It requires AES or Rijndael to be registered previously, otherwise it will
1482return \textbf{CRYPT\_NOP}.
1483
1484\subsubsection{CCM Example}
1485The following is a sample of how to call CCM.
1486
1487\begin{small}
1488\begin{verbatim}
1489#include <tomcrypt.h>
1490int main(void)
1491{
1492   unsigned char key[16], nonce[12], pt[32], ct[32],
1493                 tag[16], tagcp[16];
1494   unsigned long taglen;
1495   int           err;
1496
1497   /* register cipher */
1498   register_cipher(&aes_desc);
1499
1500   /* somehow fill key, nonce, pt */
1501
1502   /* encrypt it */
1503   taglen = sizeof(tag);
1504   if ((err =
1505       ccm_memory(find_cipher("aes"),
1506                  key, 16,    /* 128-bit key */
1507                  NULL,       /* not prescheduled */
1508                  nonce, 12,  /* 96-bit nonce */
1509                  NULL, 0,    /* no header */
1510                  pt, 32,     /* 32-byte plaintext */
1511                  ct,         /* ciphertext */
1512                  tag, &taglen,
1513                  CCM_ENCRYPT)) != CRYPT_OK) {
1514       printf("ccm_memory error %s\n", error_to_string(err));
1515       return -1;
1516   }
1517   /* ct[0..31] and tag[0..15] now hold the output */
1518
1519   /* decrypt it */
1520   taglen = sizeof(tagcp);
1521   if ((err =
1522       ccm_memory(find_cipher("aes"),
1523                  key, 16,    /* 128-bit key */
1524                  NULL,       /* not prescheduled */
1525                  nonce, 12,  /* 96-bit nonce */
1526                  NULL, 0,    /* no header */
1527                  ct, 32,     /* 32-byte ciphertext */
1528                  pt,         /* plaintext */
1529                  tagcp, &taglen,
1530                  CCM_DECRYPT)) != CRYPT_OK) {
1531       printf("ccm_memory error %s\n", error_to_string(err));
1532       return -1;
1533   }
1534
1535   /* now pt[0..31] should hold the original plaintext,
1536      tagcp[0..15] and tag[0..15] should have the same contents */
1537}
1538\end{verbatim}
1539\end{small}
1540
1541\subsection{GCM Mode}
1542Galois counter mode is an IEEE proposal for authenticated encryption (also it is a planned NIST standard).  Like EAX and OCB mode, it can be used in a streaming capacity
1543however, unlike EAX it cannot accept \textit{additional authentication data} (meta--data) after plaintext has been processed.  This mode also only works with
1544block ciphers with a 16--byte block.
1545
1546A GCM stream is meant to be processed in three modes, one after another.  First, the initial vector (per session) data is processed.  This should be
1547unique to every session.  Next, the the optional additional authentication data is processed, and finally the plaintext (or ciphertext depending on the direction).
1548
1549\subsubsection{Initialization}
1550To initialize the GCM context with a secret key call the following function.
1551
1552\index{gcm\_init()}
1553\begin{verbatim}
1554int gcm_init(          gcm_state *gcm,
1555                             int  cipher,
1556             const unsigned char *key,
1557                             int  keylen);
1558\end{verbatim}
1559This initializes the GCM state \textit{gcm} for the given cipher indexed by \textit{cipher}, with a secret key \textit{key} of length \textit{keylen} octets.  The cipher
1560chosen must have a 16--byte block size (e.g., AES).
1561
1562\subsubsection{Initial Vector}
1563After the state has been initialized (or reset) the next step is to add the session (or packet) initial vector.  It should be unique per packet encrypted.
1564
1565\index{gcm\_add\_iv()}
1566\begin{verbatim}
1567int gcm_add_iv(          gcm_state *gcm,
1568               const unsigned char *IV,
1569                     unsigned long  IVlen);
1570\end{verbatim}
1571This adds the initial vector octets from \textit{IV} of length \textit{IVlen} to the GCM state \textit{gcm}.  You can call this function as many times as required
1572to process the entire IV.
1573
1574Note: the GCM protocols provides a \textit{shortcut} for 12--byte IVs where no pre-processing is to be done.  If you want to minimize per packet latency it is ideal
1575to only use 12--byte IVs.  You can just increment it like a counter for each packet.
1576
1577\subsubsection{Additional Authentication Data}
1578After the entire IV has been processed, the additional authentication data can be processed.  Unlike the IV, a packet/session does not require additional
1579authentication data (AAD) for security.  The AAD is meant to be used as side--channel data you want to be authenticated with the packet.  Note:  once
1580you begin adding AAD to the GCM state you cannot return to adding IV data until the state has been reset.
1581
1582\index{gcm\_add\_aad()}
1583\begin{verbatim}
1584int gcm_add_aad(          gcm_state *gcm,
1585                const unsigned char *adata,
1586                      unsigned long  adatalen);
1587\end{verbatim}
1588This adds the additional authentication data \textit{adata} of length \textit{adatalen} to the GCM state \textit{gcm}.
1589
1590\subsubsection{Plaintext Processing}
1591After the AAD has been processed, the plaintext (or ciphertext depending on the direction) can be processed.
1592
1593\index{gcm\_process()}
1594\begin{verbatim}
1595int gcm_process(    gcm_state *gcm,
1596                unsigned char *pt,
1597                unsigned long  ptlen,
1598                unsigned char *ct,
1599                          int  direction);
1600\end{verbatim}
1601This processes message data where \textit{pt} is the plaintext and \textit{ct} is the ciphertext.  The length of both are equal and stored in \textit{ptlen}.  Depending on
1602the mode \textit{pt} is the input and \textit{ct} is the output (or vice versa).  When \textit{direction} equals \textbf{GCM\_ENCRYPT} the plaintext is read,
1603encrypted and stored in the ciphertext buffer.  When \textit{direction} equals \textbf{GCM\_DECRYPT} the opposite occurs.
1604
1605\subsubsection{State Termination}
1606To terminate a GCM state and retrieve the message authentication tag call the following function.
1607
1608\index{gcm\_done()}
1609\begin{verbatim}
1610int gcm_done(    gcm_state *gcm,
1611             unsigned char *tag,
1612             unsigned long *taglen);
1613\end{verbatim}
1614This terminates the GCM state \textit{gcm} and stores the tag in \textit{tag} of length \textit{taglen} octets.
1615
1616\subsubsection{State Reset}
1617The call to gcm\_init() will perform considerable pre--computation (when \textbf{GCM\_TABLES} is defined) and if you're going to be dealing with a lot of packets
1618it is very costly to have to call it repeatedly.  To aid in this endeavour, the reset function has been provided.
1619
1620\index{gcm\_reset()}
1621\begin{verbatim}
1622int gcm_reset(gcm_state *gcm);
1623\end{verbatim}
1624
1625This will reset the GCM state \textit{gcm} to the state that gcm\_init() left it.  The user would then call gcm\_add\_iv(), gcm\_add\_aad(), etc.
1626
1627\subsubsection{One--Shot Packet}
1628To process a single packet under any given key the following helper function can be used.
1629
1630\index{gcm\_memory()}
1631\begin{verbatim}
1632int gcm_memory(
1633                    int  cipher,
1634    const unsigned char *key,
1635          unsigned long keylen,
1636    const unsigned char *IV,    unsigned long IVlen,
1637    const unsigned char *adata, unsigned long adatalen,
1638          unsigned char *pt,    unsigned long ptlen,
1639          unsigned char *ct,
1640          unsigned char *tag,   unsigned long *taglen,
1641                    int  direction);
1642\end{verbatim}
1643
1644This will initialize the GCM state with the given key, IV and AAD value then proceed to encrypt or decrypt the message text and store the final
1645message tag.  The definition of the variables is the same as it is for all the manual functions.
1646
1647If you are processing many packets under the same key you shouldn't use this function as it invokes the pre--computation with each call.
1648
1649\subsubsection{Example Usage}
1650The following is an example usage of how to use GCM over multiple packets with a shared secret key.
1651
1652\begin{small}
1653\begin{verbatim}
1654#include <tomcrypt.h>
1655
1656int send_packet(const unsigned char *pt,  unsigned long ptlen,
1657                const unsigned char *iv,  unsigned long ivlen,
1658                const unsigned char *aad, unsigned long aadlen,
1659                      gcm_state     *gcm)
1660{
1661   int           err;
1662   unsigned long taglen;
1663   unsigned char tag[16];
1664
1665   /* reset the state */
1666   if ((err = gcm_reset(gcm)) != CRYPT_OK) {
1667      return err;
1668   }
1669
1670   /* Add the IV */
1671   if ((err = gcm_add_iv(gcm, iv, ivlen)) != CRYPT_OK) {
1672      return err;
1673   }
1674
1675   /* Add the AAD (note: aad can be NULL if aadlen == 0) */
1676   if ((err = gcm_add_aad(gcm, aad, aadlen)) != CRYPT_OK) {
1677      return err;
1678   }
1679
1680   /* process the plaintext */
1681   if ((err =
1682        gcm_process(gcm, pt, ptlen, pt, GCM_ENCRYPT)) != CRYPT_OK) {
1683      return err;
1684   }
1685
1686   /* Finish up and get the MAC tag */
1687   taglen = sizeof(tag);
1688   if ((err = gcm_done(gcm, tag, &taglen)) != CRYPT_OK) {
1689      return err;
1690   }
1691
1692   /* ... send a header describing the lengths ... */
1693
1694   /* depending on the protocol and how IV is
1695    * generated you may have to send it too... */
1696   send(socket, iv, ivlen, 0);
1697
1698   /* send the aad */
1699   send(socket, aad, aadlen, 0);
1700
1701   /* send the ciphertext */
1702   send(socket, pt, ptlen, 0);
1703
1704   /* send the tag */
1705   send(socket, tag, taglen, 0);
1706
1707   return CRYPT_OK;
1708}
1709
1710int main(void)
1711{
1712   gcm_state     gcm;
1713   unsigned char key[16], IV[12], pt[PACKET_SIZE];
1714   int           err, x;
1715   unsigned long ptlen;
1716
1717   /* somehow fill key/IV with random values */
1718
1719   /* register AES */
1720   register_cipher(&aes_desc);
1721
1722   /* init the GCM state */
1723   if ((err =
1724        gcm_init(&gcm, find_cipher("aes"), key, 16)) != CRYPT_OK) {
1725      whine_and_pout(err);
1726   }
1727
1728   /* handle us some packets */
1729   for (;;) {
1730       ptlen = make_packet_we_want_to_send(pt);
1731
1732       /* use IV as counter (12 byte counter) */
1733       for (x = 11; x >= 0; x--) {
1734           if (++IV[x]) {
1735              break;
1736           }
1737       }
1738
1739       if ((err = send_packet(pt, ptlen, iv, 12, NULL, 0, &gcm))
1740           != CRYPT_OK) {
1741           whine_and_pout(err);
1742       }
1743   }
1744   return EXIT_SUCCESS;
1745}
1746\end{verbatim}
1747\end{small}
1748
1749\chapter{One-Way Cryptographic Hash Functions}
1750\mysection{Core Functions}
1751Like the ciphers, there are hash core functions and a universal data type to hold the hash state called \textit{hash\_state}.  To initialize hash
1752XXX (where XXX is the name) call:
1753\index{Hash Functions}
1754\begin{verbatim}
1755void XXX_init(hash_state *md);
1756\end{verbatim}
1757
1758This 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:
1759\begin{verbatim}
1760int XXX_process(         hash_state *md,
1761                const unsigned char *in,
1762                      unsigned long  inlen);
1763\end{verbatim}
1764Essentially 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
1765are 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,
1766this means that:
1767\begin{verbatim}
1768md5_process(&md, "hello ", 6);
1769md5_process(&md, "world", 5);
1770\end{verbatim}
1771Will produce the same message digest as the single call:
1772\index{Message Digest}
1773\begin{verbatim}
1774md5_process(&md, "hello world", 11);
1775\end{verbatim}
1776
1777To finally get the message digest (the hash) call:
1778\begin{verbatim}
1779int XXX_done(   hash_state *md,
1780             unsigned char *out);
1781\end{verbatim}
1782
1783This function will finish up the hash and store the result in the \textit{out} array.  You must ensure that \textit{out} is long
1784enough for the hash in question.  Often hashes are used to get keys for symmetric ciphers so the \textit{XXX\_done()} functions
1785will wipe the \textit{md} variable before returning automatically.
1786
1787To test a hash function call:
1788\begin{verbatim}
1789int XXX_test(void);
1790\end{verbatim}
1791
1792This will return {\bf CRYPT\_OK} if the hash matches the test vectors, otherwise it returns an error code.  An
1793example snippet that hashes a message with md5 is given below.
1794\begin{small}
1795\begin{verbatim}
1796#include <tomcrypt.h>
1797int main(void)
1798{
1799    hash_state md;
1800    unsigned char *in = "hello world", out[16];
1801
1802    /* setup the hash */
1803    md5_init(&md);
1804
1805    /* add the message */
1806    md5_process(&md, in, strlen(in));
1807
1808    /* get the hash in out[0..15] */
1809    md5_done(&md, out);
1810
1811    return 0;
1812}
1813\end{verbatim}
1814\end{small}
1815
1816\mysection{Hash Descriptors}
1817Like the set of ciphers, the set of hashes have descriptors as well.  They are stored in an array called \textit{hash\_descriptor} and
1818are defined by:
1819\begin{verbatim}
1820struct _hash_descriptor {
1821    char *name;
1822
1823    unsigned long hashsize;    /* digest output size in bytes  */
1824    unsigned long blocksize;   /* the block size the hash uses */
1825
1826    void (*init)   (hash_state *hash);
1827
1828    int  (*process)(         hash_state *hash,
1829                    const unsigned char *in,
1830                          unsigned long  inlen);
1831
1832    int  (*done)   (hash_state *hash, unsigned char *out);
1833
1834    int  (*test)   (void);
1835};
1836\end{verbatim}
1837
1838\index{find\_hash()}
1839The \textit{name} member is the name of the hash function (all lowercase).  The \textit{hashsize} member is the size of the digest output
1840in bytes, while \textit{blocksize} is the size of blocks the hash expects to the compression function.  Technically, this detail is not important
1841for high level developers but is useful to know for performance reasons.
1842
1843The \textit{init} member initializes the hash, \textit{process} passes data through the hash, \textit{done} terminates the hash and retrieves the
1844digest.  The \textit{test} member tests the hash against the specified test vectors.
1845
1846There is a function to search the array as well called \textit{int find\_hash(char *name)}.  It returns -1 if the hash is not found, otherwise, the
1847position in the descriptor table of the hash.
1848
1849In addition, there is also find\_hash\_oid() which finds a hash by the ASN.1 OBJECT IDENTIFIER string.
1850\index{find\_hash\_oid()}
1851\begin{verbatim}
1852int find_hash_oid(const unsigned long *ID, unsigned long IDlen);
1853\end{verbatim}
1854
1855You can use the table to indirectly call a hash function that is chosen at run-time.  For example:
1856\begin{small}
1857\begin{verbatim}
1858#include <tomcrypt.h>
1859int main(void)
1860{
1861   unsigned char buffer[100], hash[MAXBLOCKSIZE];
1862   int idx, x;
1863   hash_state md;
1864
1865   /* register hashes .... */
1866   if (register_hash(&md5_desc) == -1) {
1867      printf("Error registering MD5.\n");
1868      return -1;
1869   }
1870
1871   /* register other hashes ... */
1872
1873   /* prompt for name and strip newline */
1874   printf("Enter hash name: \n");
1875   fgets(buffer, sizeof(buffer), stdin);
1876   buffer[strlen(buffer) - 1] = 0;
1877
1878   /* get hash index */
1879   idx = find_hash(buffer);
1880   if (idx == -1) {
1881      printf("Invalid hash name!\n");
1882      return -1;
1883   }
1884
1885   /* hash input until blank line */
1886   hash_descriptor[idx].init(&md);
1887   while (fgets(buffer, sizeof(buffer), stdin) != NULL)
1888         hash_descriptor[idx].process(&md, buffer, strlen(buffer));
1889   hash_descriptor[idx].done(&md, hash);
1890
1891   /* dump to screen */
1892   for (x = 0; x < hash_descriptor[idx].hashsize; x++)
1893       printf("%02x ", hash[x]);
1894   printf("\n");
1895   return 0;
1896}
1897\end{verbatim}
1898\end{small}
1899
1900Note the usage of \textbf{MAXBLOCKSIZE}.  In LibTomCrypt, no symmetric block, key or hash digest is larger than \textbf{MAXBLOCKSIZE} in
1901length.  This provides a simple size you can set your automatic arrays to that will not get overrun.
1902
1903There are three helper functions to make working with hashes easier.  The first is a function to hash a buffer, and produce the digest in a single
1904function call.
1905
1906\index{hash\_memory()}
1907\begin{verbatim}
1908int hash_memory(                int  hash,
1909                const unsigned char *in,
1910                      unsigned long  inlen,
1911                      unsigned char *out,
1912                      unsigned long *outlen);
1913\end{verbatim}
1914
1915This will hash the data pointed to by \textit{in} of length \textit{inlen}.  The hash used is indexed by the \textit{hash} parameter.  The message
1916digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size.
1917
1918The next helper function allows for the hashing of a file based on a file name.
1919\index{hash\_file()}
1920\begin{verbatim}
1921int hash_file(          int  hash,
1922                 const char *fname,
1923              unsigned char *out,
1924              unsigned long *outlen);
1925\end{verbatim}
1926
1927This will hash the file named by \textit{fname} using the hash indexed by \textit{hash}.  The file named in this function call must be readable by the
1928user owning the process performing the request.  This function can be omitted by the \textbf{LTC\_NO\_FILE} define, which forces it to return \textbf{CRYPT\_NOP}
1929when it is called.  The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size.
1930
1931\index{hash\_filehandle()}
1932\begin{verbatim}
1933int hash_filehandle(          int  hash,
1934                             FILE *in,
1935                    unsigned char *out,
1936                    unsigned long *outlen);
1937\end{verbatim}
1938
1939This will hash the file identified by the handle \textit{in} using the hash indexed by \textit{hash}.  This will begin hashing from the current file pointer position, and
1940will not rewind the file pointer when finished.  This function can be omitted by the \textbf{LTC\_NO\_FILE} define, which forces it to return \textbf{CRYPT\_NOP}
1941when it is called.  The message digest is stored in \textit{out}, and the \textit{outlen} parameter is updated to hold the message digest size.
1942
1943To perform the above hash with md5 the following code could be used:
1944\begin{small}
1945\begin{verbatim}
1946#include <tomcrypt.h>
1947int main(void)
1948{
1949   int idx, err;
1950   unsigned long len;
1951   unsigned char out[MAXBLOCKSIZE];
1952
1953   /* register the hash */
1954   if (register_hash(&md5_desc) == -1) {
1955      printf("Error registering MD5.\n");
1956      return -1;
1957   }
1958
1959   /* get the index of the hash  */
1960   idx = find_hash("md5");
1961
1962   /* call the hash */
1963   len = sizeof(out);
1964   if ((err =
1965       hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) {
1966      printf("Error hashing data: %s\n", error_to_string(err));
1967      return -1;
1968   }
1969   return 0;
1970}
1971\end{verbatim}
1972\end{small}
1973
1974\subsection{Hash Registration}
1975Similar to the cipher descriptor table you must register your hash algorithms before you can use them.  These functions
1976work exactly like those of the cipher registration code.  The functions are:
1977\index{register\_hash()} \index{unregister\_hash()}
1978\begin{verbatim}
1979int register_hash(const struct _hash_descriptor *hash);
1980
1981int unregister_hash(const struct _hash_descriptor *hash);
1982\end{verbatim}
1983
1984The following hashes are provided as of this release within the LibTomCrypt library:
1985\index{Hash descriptor table}
1986
1987\begin{figure}[here]
1988\begin{center}
1989\begin{tabular}{|c|c|c|}
1990      \hline \textbf{Name} & \textbf{Descriptor Name} & \textbf{Size of Message Digest (bytes)} \\
1991      \hline WHIRLPOOL & whirlpool\_desc & 64 \\
1992      \hline SHA-512 & sha512\_desc & 64 \\
1993      \hline SHA-384 & sha384\_desc & 48 \\
1994      \hline RIPEMD-320 & rmd160\_desc & 40 \\
1995      \hline SHA-256 & sha256\_desc & 32 \\
1996      \hline RIPEMD-256 & rmd160\_desc & 32 \\
1997      \hline SHA-224 & sha224\_desc & 28 \\
1998      \hline TIGER-192 & tiger\_desc & 24 \\
1999      \hline SHA-1 & sha1\_desc & 20 \\
2000      \hline RIPEMD-160 & rmd160\_desc & 20 \\
2001      \hline RIPEMD-128 & rmd128\_desc & 16 \\
2002      \hline MD5 & md5\_desc & 16 \\
2003      \hline MD4 & md4\_desc & 16 \\
2004      \hline MD2 & md2\_desc & 16 \\
2005      \hline
2006\end{tabular}
2007\end{center}
2008\caption{Built--In Software Hashes}
2009\end{figure}
2010\vfil
2011
2012\mysection{Cipher Hash Construction}
2013\index{Cipher Hash Construction}
2014An addition to the suite of hash functions is the \textit{Cipher Hash Construction} or \textit{CHC} mode.  In this mode
2015applicable block ciphers (such as AES) can be turned into hash functions that other LTC functions can use.  In
2016particular this allows a cryptosystem to be designed using very few moving parts.
2017
2018In order to use the CHC system the developer will have to take a few extra steps.  First the \textit{chc\_desc} hash
2019descriptor must be registered with register\_hash().  At this point the CHC hash cannot be used to hash
2020data.  While it is in the hash system you still have to tell the CHC code which cipher to use.  This is accomplished
2021via the chc\_register() function.
2022
2023\index{chc\_register()}
2024\begin{verbatim}
2025int chc_register(int cipher);
2026\end{verbatim}
2027
2028A cipher has to be registered with CHC (and also in the cipher descriptor tables with
2029register\_cipher()).  The chc\_register() function will bind a cipher to the CHC system.  Only one cipher can
2030be bound to the CHC hash at a time.  There are additional requirements for the system to work.
2031
2032\begin{enumerate}
2033   \item The cipher must have a block size greater than 64--bits.
2034   \item The cipher must allow an input key the size of the block size.
2035\end{enumerate}
2036
2037Example of using CHC with the AES block cipher.
2038
2039\begin{verbatim}
2040#include <tomcrypt.h>
2041int main(void)
2042{
2043   int err;
2044
2045   /* register cipher and hash */
2046   if (register_cipher(&aes_enc_desc) == -1) {
2047      printf("Could not register cipher\n");
2048      return EXIT_FAILURE;
2049   }
2050   if (register_hash(&chc_desc) == -1) {
2051      printf("Could not register hash\n");
2052      return EXIT_FAILURE;
2053   }
2054
2055   /* start chc with AES */
2056   if ((err = chc_register(find_cipher("aes"))) != CRYPT_OK) {
2057      printf("Error binding AES to CHC: %s\n",
2058             error_to_string(err));
2059   }
2060
2061   /* now you can use chc_hash in any LTC function
2062    * [aside from pkcs...] */
2063}
2064\end{verbatim}
2065
2066
2067\mysection{Notice}
2068It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes.
2069These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators
2070(e.g. Yarrow).
2071
2072The 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
2073for all purposes you would normally use a hash for.
2074
2075\chapter{Message Authentication Codes}
2076\mysection{HMAC Protocol}
2077Thanks to Dobes Vandermeer, the library now includes support for hash based message authentication codes, or HMAC for short.  An HMAC
2078of a message is a keyed authentication code that only the owner of a private symmetric key will be able to verify.  The purpose is
2079to 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
2080eavesdropper will not be able to verify the authenticity of a message.
2081
2082The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key
2083and 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
2084unsigned characters.  The initialization routine is:
2085\index{hmac\_init()}
2086\begin{verbatim}
2087int hmac_init(         hmac_state *hmac,
2088                              int  hash,
2089              const unsigned char *key,
2090                    unsigned long  keylen);
2091\end{verbatim}
2092The \textit{hmac} parameter is the state for the HMAC code.  The \textit{hash} parameter is the index into the descriptor table of the hash you want
2093to use to authenticate the message.  The \textit{key} parameter is the pointer to the array of chars that make up the key.  The \textit{keylen} parameter is the
2094length (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:
2095\index{hmac\_process()}
2096\begin{verbatim}
2097int hmac_process(         hmac_state *hmac,
2098                 const unsigned char *in,
2099                       unsigned long  inlen);
2100\end{verbatim}
2101\textit{hmac} is the HMAC state you are working with. \textit{buf} is the array of octets to send into the HMAC process.  \textit{len} is the
2102number of octets to process.  Like the hash process routines you can send the data in arbitrarily sized chunks. When you
2103are finished with the HMAC process you must call the following function to get the HMAC code:
2104\index{hmac\_done()}
2105\begin{verbatim}
2106int hmac_done(   hmac_state *hmac,
2107              unsigned char *out,
2108              unsigned long *outlen);
2109\end{verbatim}
2110The \textit{hmac} parameter is the HMAC state you are working with.  The \textit{out} parameter is the array of octets where the HMAC code should be stored.
2111You must set \textit{outlen} to the size of the destination buffer before calling this function.  It is updated with the length of the HMAC code
2112produced (depending on which hash was picked).  If \textit{outlen} is less than the size of the message digest (and ultimately
2113the HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first \textit{outlen} bytes).
2114
2115There are two utility functions provided to make using HMACs easier to do.  They accept the key and information about the
2116message (file pointer, address in memory), and produce the HMAC result in one shot.  These are useful if you want to avoid
2117calling the three step process yourself.
2118
2119\index{hmac\_memory()}
2120\begin{verbatim}
2121int hmac_memory(
2122                   int  hash,
2123   const unsigned char *key, unsigned long  keylen,
2124   const unsigned char *in,  unsigned long  inlen,
2125         unsigned char *out, unsigned long *outlen);
2126\end{verbatim}
2127This will produce an HMAC code for the array of octets in \textit{in} of length \textit{inlen}.  The index into the hash descriptor
2128table must be provided in \textit{hash}.  It uses the key from \textit{key} with a key length of \textit{keylen}.
2129The result is stored in the array of octets \textit{out} and the length in \textit{outlen}.  The value of \textit{outlen} must be set
2130to the size of the destination buffer before calling this function.  Similarly for files there is the  following function:
2131\index{hmac\_file()}
2132\begin{verbatim}
2133int hmac_file(
2134                   int  hash,
2135            const char *fname,
2136   const unsigned char *key, unsigned long  keylen,
2137         unsigned char *out, unsigned long *outlen);
2138\end{verbatim}
2139\textit{hash} is the index into the hash descriptor table of the hash you want to use.  \textit{fname} is the filename to process.
2140\textit{key} is the array of octets to use as the key of length \textit{keylen}.  \textit{out} is the array of octets where the
2141result should be stored.
2142
2143To test if the HMAC code is working there is the following function:
2144\index{hmac\_test()}
2145\begin{verbatim}
2146int hmac_test(void);
2147\end{verbatim}
2148Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code.  Some example code for using the
2149HMAC system is given below.
2150
2151\begin{small}
2152\begin{verbatim}
2153#include <tomcrypt.h>
2154int main(void)
2155{
2156   int idx, err;
2157   hmac_state hmac;
2158   unsigned char key[16], dst[MAXBLOCKSIZE];
2159   unsigned long dstlen;
2160
2161   /* register SHA-1 */
2162   if (register_hash(&sha1_desc) == -1) {
2163      printf("Error registering SHA1\n");
2164      return -1;
2165   }
2166
2167   /* get index of SHA1 in hash descriptor table */
2168   idx = find_hash("sha1");
2169
2170   /* we would make up our symmetric key in "key[]" here */
2171
2172   /* start the HMAC */
2173   if ((err = hmac_init(&hmac, idx, key, 16)) != CRYPT_OK) {
2174      printf("Error setting up hmac: %s\n", error_to_string(err));
2175      return -1;
2176   }
2177
2178   /* process a few octets */
2179   if((err = hmac_process(&hmac, "hello", 5) != CRYPT_OK) {
2180      printf("Error processing hmac: %s\n", error_to_string(err));
2181      return -1;
2182   }
2183
2184   /* get result (presumably to use it somehow...) */
2185   dstlen = sizeof(dst);
2186   if ((err = hmac_done(&hmac, dst, &dstlen)) != CRYPT_OK) {
2187      printf("Error finishing hmac: %s\n", error_to_string(err));
2188      return -1;
2189   }
2190   printf("The hmac is %lu bytes long\n", dstlen);
2191
2192   /* return */
2193   return 0;
2194}
2195\end{verbatim}
2196\end{small}
2197
2198\mysection{OMAC Support}
2199\index{OMAC} \index{CMAC}
2200OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an
2201algorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES.  Note:  OMAC has been standardized as
2202CMAC within NIST, for the purposes of this library OMAC and CMAC are synonymous.  From an API standpoint, the OMAC routines work much like the
2203HMAC routines.  Instead, in this case a cipher is used instead of a hash.
2204
2205To start an OMAC state you call
2206\index{omac\_init()}
2207\begin{verbatim}
2208int omac_init(         omac_state *omac,
2209                              int  cipher,
2210              const unsigned char *key,
2211                    unsigned long  keylen);
2212\end{verbatim}
2213The \textit{omac} parameter is the state for the OMAC algorithm.  The \textit{cipher} parameter is the index into the cipher\_descriptor table
2214of the cipher\footnote{The cipher must have a 64 or 128 bit block size.  Such as CAST5, Blowfish, DES, AES, Twofish, etc.} you
2215wish to use.  The \textit{key} and \textit{keylen} parameters are the keys used to authenticate the data.
2216
2217To send data through the algorithm call
2218\index{omac\_process()}
2219\begin{verbatim}
2220int omac_process(         omac_state *state,
2221                 const unsigned char *in,
2222                       unsigned long  inlen);
2223\end{verbatim}
2224This will send \textit{inlen} bytes from \textit{in} through the active OMAC state \textit{state}.  Returns \textbf{CRYPT\_OK} if the
2225function succeeds.  The function is not sensitive to the granularity of the data.  For example,
2226
2227\begin{verbatim}
2228omac_process(&mystate, "hello",  5);
2229omac_process(&mystate, " world", 6);
2230\end{verbatim}
2231
2232Would produce the same result as,
2233
2234\begin{verbatim}
2235omac_process(&mystate, "hello world",  11);
2236\end{verbatim}
2237
2238When you are done processing the message you can call the following to compute the message tag.
2239
2240\index{omac\_done()}
2241\begin{verbatim}
2242int omac_done(   omac_state *state,
2243              unsigned char *out,
2244              unsigned long *outlen);
2245\end{verbatim}
2246Which will terminate the OMAC and output the \textit{tag} (MAC) to \textit{out}.  Note that unlike the HMAC and other code
2247\textit{outlen} can be smaller than the default MAC size (for instance AES would make a 16-byte tag).  Part of the OMAC
2248specification states that the output may be truncated.  So if you pass in $outlen = 5$ and use AES as your cipher than
2249the output MAC code will only be five bytes long.  If \textit{outlen} is larger than the default size it is set to the default
2250size to show how many bytes were actually used.
2251
2252Similar to the HMAC code the file and memory functions are also provided.  To OMAC a buffer of memory in one shot use the
2253following function.
2254
2255\index{omac\_memory()}
2256\begin{verbatim}
2257int omac_memory(
2258                    int  cipher,
2259    const unsigned char *key, unsigned long keylen,
2260    const unsigned char *in,  unsigned long inlen,
2261          unsigned char *out, unsigned long *outlen);
2262\end{verbatim}
2263This will compute the OMAC of \textit{inlen} bytes of \textit{in} using the key \textit{key} of length \textit{keylen} bytes and the cipher
2264specified by the \textit{cipher}'th entry in the cipher\_descriptor table.  It will store the MAC in \textit{out} with the same
2265rules as omac\_done.
2266
2267To OMAC a file use
2268\index{omac\_file()}
2269\begin{verbatim}
2270int omac_file(
2271                    int  cipher,
2272    const unsigned char *key,      unsigned long keylen,
2273             const char *filename,
2274          unsigned char *out,      unsigned long *outlen);
2275\end{verbatim}
2276
2277Which will OMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes
2278and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table.  It will store the MAC in \textit{out} with
2279the same rules as omac\_done.
2280
2281To test if the OMAC code is working there is the following function:
2282\index{omac\_test()}
2283\begin{verbatim}
2284int omac_test(void);
2285\end{verbatim}
2286Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code.  Some example code for using the
2287OMAC system is given below.
2288
2289\begin{small}
2290\begin{verbatim}
2291#include <tomcrypt.h>
2292int main(void)
2293{
2294   int idx, err;
2295   omac_state omac;
2296   unsigned char key[16], dst[MAXBLOCKSIZE];
2297   unsigned long dstlen;
2298
2299   /* register Rijndael */
2300   if (register_cipher(&rijndael_desc) == -1) {
2301      printf("Error registering Rijndael\n");
2302      return -1;
2303   }
2304
2305   /* get index of Rijndael in cipher descriptor table */
2306   idx = find_cipher("rijndael");
2307
2308   /* we would make up our symmetric key in "key[]" here */
2309
2310   /* start the OMAC */
2311   if ((err = omac_init(&omac, idx, key, 16)) != CRYPT_OK) {
2312      printf("Error setting up omac: %s\n", error_to_string(err));
2313      return -1;
2314   }
2315
2316   /* process a few octets */
2317   if((err = omac_process(&omac, "hello", 5) != CRYPT_OK) {
2318      printf("Error processing omac: %s\n", error_to_string(err));
2319      return -1;
2320   }
2321
2322   /* get result (presumably to use it somehow...) */
2323   dstlen = sizeof(dst);
2324   if ((err = omac_done(&omac, dst, &dstlen)) != CRYPT_OK) {
2325      printf("Error finishing omac: %s\n", error_to_string(err));
2326      return -1;
2327   }
2328   printf("The omac is %lu bytes long\n", dstlen);
2329
2330   /* return */
2331   return 0;
2332}
2333\end{verbatim}
2334\end{small}
2335
2336\mysection{PMAC Support}
2337The PMAC\footnote{J.Black, P.Rogaway, \textit{A Block--Cipher Mode of Operation for Parallelizable Message Authentication}}
2338protocol is another MAC algorithm that relies solely on a symmetric-key block cipher.  It uses essentially the same
2339API as the provided OMAC code.
2340
2341A PMAC state is initialized with the following.
2342
2343\index{pmac\_init()}
2344\begin{verbatim}
2345int pmac_init(         pmac_state *pmac,
2346                              int  cipher,
2347              const unsigned char *key,
2348                    unsigned long  keylen);
2349\end{verbatim}
2350Which initializes the \textit{pmac} state with the given \textit{cipher} and \textit{key} of length \textit{keylen} bytes.  The chosen cipher
2351must have a 64 or 128 bit block size (e.x. AES).
2352
2353To MAC data simply send it through the process function.
2354
2355\index{pmac\_process()}
2356\begin{verbatim}
2357int pmac_process(         pmac_state *state,
2358                 const unsigned char *in,
2359                       unsigned long  inlen);
2360\end{verbatim}
2361This will process \textit{inlen} bytes of \textit{in} in the given \textit{state}.  The function is not sensitive to the granularity of the
2362data.  For example,
2363
2364\begin{verbatim}
2365pmac_process(&mystate, "hello",  5);
2366pmac_process(&mystate, " world", 6);
2367\end{verbatim}
2368
2369Would produce the same result as,
2370
2371\begin{verbatim}
2372pmac_process(&mystate, "hello world",  11);
2373\end{verbatim}
2374
2375When a complete message has been processed the following function can be called to compute the message tag.
2376
2377\index{pmac\_done()}
2378\begin{verbatim}
2379int pmac_done(   pmac_state *state,
2380              unsigned char *out,
2381              unsigned long *outlen);
2382\end{verbatim}
2383This will store up to \textit{outlen} bytes of the tag for the given \textit{state} into \textit{out}.  Note that if \textit{outlen} is larger
2384than the size of the tag it is set to the amount of bytes stored in \textit{out}.
2385
2386Similar to the OMAC code the file and memory functions are also provided.  To PMAC a buffer of memory in one shot use the
2387following function.
2388
2389\index{pmac\_memory()}
2390\begin{verbatim}
2391int pmac_memory(
2392                    int  cipher,
2393    const unsigned char *key, unsigned long  keylen,
2394    const unsigned char *in,  unsigned long  inlen,
2395          unsigned char *out, unsigned long *outlen);
2396\end{verbatim}
2397This will compute the PMAC of \textit{msglen} bytes of \textit{msg} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2398specified by the \textit{cipher}'th entry in the cipher\_descriptor table.  It will store the MAC in \textit{out} with the same
2399rules as pmac\_done().
2400
2401To PMAC a file use
2402\index{pmac\_file()}
2403\begin{verbatim}
2404int pmac_file(
2405                    int  cipher,
2406    const unsigned char *key,      unsigned long keylen,
2407             const char *filename,
2408          unsigned char *out,      unsigned long *outlen);
2409\end{verbatim}
2410
2411Which will PMAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes,
2412and the cipher specified by the \textit{cipher}'th entry in the cipher\_descriptor table.  It will store the MAC in \textit{out} with
2413the same rules as pmac\_done().
2414
2415To test if the PMAC code is working there is the following function:
2416\index{pmac\_test()}
2417\begin{verbatim}
2418int pmac_test(void);
2419\end{verbatim}
2420Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code.
2421
2422\mysection{Pelican MAC}
2423Pelican MAC is a new (experimental) MAC by the AES team that uses four rounds of AES as a \textit{mixing function}.  It achieves a very high
2424rate of processing and is potentially very secure.  It requires AES to be enabled to function.  You do not have to register\_cipher() AES first though
2425as it calls AES directly.
2426
2427\index{pelican\_init()}
2428\begin{verbatim}
2429int pelican_init(      pelican_state *pelmac,
2430                 const unsigned char *key,
2431                       unsigned long  keylen);
2432\end{verbatim}
2433This will initialize the Pelican state with the given AES key.  Once this has been done you can begin processing data.
2434
2435\index{pelican\_process()}
2436\begin{verbatim}
2437int pelican_process(      pelican_state *pelmac,
2438                    const unsigned char *in,
2439                          unsigned long  inlen);
2440\end{verbatim}
2441This will process \textit{inlen} bytes of \textit{in} through the Pelican MAC.  It's best that you pass in multiples of 16 bytes as it makes the
2442routine more efficient but you may pass in any length of text.  You can call this function as many times as required to process
2443an entire message.
2444
2445\index{pelican\_done()}
2446\begin{verbatim}
2447int pelican_done(pelican_state *pelmac, unsigned char *out);
2448\end{verbatim}
2449This terminates a Pelican MAC and writes the 16--octet tag to \textit{out}.
2450
2451\subsection{Example}
2452
2453\begin{verbatim}
2454#include <tomcrypt.h>
2455int main(void)
2456{
2457   pelican_state pelstate;
2458   unsigned char key[32], tag[16];
2459   int           err;
2460
2461   /* somehow initialize a key */
2462
2463   /* initialize pelican mac */
2464   if ((err = pelican_init(&pelstate, /* the state */
2465                           key,       /* user key */
2466                           32         /* key length in octets */
2467                          )) != CRYPT_OK) {
2468      printf("Error initializing Pelican: %s",
2469              error_to_string(err));
2470      return EXIT_FAILURE;
2471   }
2472
2473   /* MAC some data */
2474   if ((err = pelican_process(&pelstate,       /* the state */
2475                              "hello world",   /* data to mac */
2476                              11               /* length of data */
2477                              )) != CRYPT_OK) {
2478      printf("Error processing Pelican: %s",
2479             error_to_string(err));
2480      return EXIT_FAILURE;
2481   }
2482
2483   /* Terminate the MAC */
2484   if ((err = pelican_done(&pelstate,/* the state */
2485                           tag       /* where to store the tag */
2486                           )) != CRYPT_OK) {
2487      printf("Error terminating Pelican: %s",
2488             error_to_string(err));
2489      return EXIT_FAILURE;
2490   }
2491
2492   /* tag[0..15] has the MAC output now */
2493
2494   return EXIT_SUCCESS;
2495}
2496\end{verbatim}
2497
2498\mysection{XCBC-MAC}
2499As of LibTomCrypt v1.15, XCBC-MAC (RFC 3566) has been provided to support TLS encryption suites.  Like OMAC, it computes a message authentication code
2500by using a cipher in CBC mode.  It also uses a single key which it expands into the requisite three keys for the MAC function.  A XCBC--MAC state is
2501initialized with the following function:
2502
2503\index{xcbc\_init()}
2504\begin{verbatim}
2505int xcbc_init(         xcbc_state *xcbc,
2506                              int  cipher,
2507              const unsigned char *key,
2508                    unsigned long  keylen);
2509\end{verbatim}
2510
2511This will initialize the XCBC--MAC state \textit{xcbc}, with the key specified in \textit{key} of length \textit{keylen} octets.  The cipher indicated
2512by the \textit{cipher} index can be either a 64 or 128--bit block cipher.  This will return \textbf{CRYPT\_OK} on success.
2513
2514To process data through XCBC--MAC use the following function:
2515
2516\index{xcbc\_process()}
2517\begin{verbatim}
2518int xcbc_process(         xcbc_state *state,
2519                 const unsigned char *in,
2520                       unsigned long  inlen);
2521\end{verbatim}
2522
2523This will add the message octets pointed to by \textit{in} of length \textit{inlen} to the XCBC--MAC state pointed to by \textit{state}.  Like the other MAC functions,
2524the granularity of the input is not important but the order is.  This will return \textbf{CRYPT\_OK} on success.
2525
2526To compute the MAC tag value use the following function:
2527
2528\index{xcbc\_done()}
2529\begin{verbatim}
2530int xcbc_done(   xcbc_state *state,
2531              unsigned char *out,
2532              unsigned long *outlen);
2533\end{verbatim}
2534
2535This will retrieve the XCBC--MAC tag from the state pointed to by \textit{state}, and store it in the array pointed to by \textit{out}.  The \textit{outlen} parameter
2536specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when the function returns.  This will return \textbf{CRYPT\_OK} on success.
2537
2538Helper functions are provided to make parsing memory buffers and files easier.  The following functions are provided:
2539
2540\index{xcbc\_memory()}
2541\begin{verbatim}
2542int xcbc_memory(
2543                    int  cipher,
2544    const unsigned char *key, unsigned long  keylen,
2545    const unsigned char *in,  unsigned long  inlen,
2546          unsigned char *out, unsigned long *outlen);
2547\end{verbatim}
2548This will compute the XCBC--MAC of \textit{msglen} bytes of \textit{msg}, using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2549specified by the \textit{cipher}'th entry in the cipher\_descriptor table.  It will store the MAC in \textit{out} with the same rules as xcbc\_done().
2550
2551To xcbc a file use
2552\index{xcbc\_file()}
2553\begin{verbatim}
2554int xcbc_file(
2555                    int  cipher,
2556    const unsigned char *key,      unsigned long keylen,
2557             const char *filename,
2558          unsigned char *out,      unsigned long *outlen);
2559\end{verbatim}
2560
2561Which will XCBC--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2562specified by the \textit{cipher}'th entry in the cipher\_descriptor table.  It will store the MAC in \textit{out} with the same rules as xcbc\_done().
2563
2564
2565To test XCBC--MAC for RFC 3566 compliance use the following function:
2566
2567\index{xcbc\_test()}
2568\begin{verbatim}
2569int xcbc_test(void);
2570\end{verbatim}
2571
2572This will return \textbf{CRYPT\_OK} on success.  This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return
2573\textbf{CRYPT\_NOP}.
2574
2575\mysection{F9--MAC}
2576The F9--MAC is yet another CBC--MAC variant proposed for the 3GPP standard.  Originally specified to be used with the KASUMI block cipher, it can also be used
2577with other ciphers.  For LibTomCrypt, the F9--MAC code can use any cipher.
2578
2579\subsection{Usage Notice}
2580F9--MAC differs slightly from the other MAC functions in that it requires the caller to perform the final message padding.  The padding quite simply is a direction
2581bit followed by a 1 bit and enough zeros to make the message a multiple of the cipher block size.  If the message is byte aligned, the padding takes on the form of
2582a single 0x40 or 0xC0 byte followed by enough 0x00 bytes to make the message proper multiple.
2583
2584If the user simply wants a MAC function (hint: use OMAC) padding with a single 0x40 byte should be sufficient for security purposes and still be reasonably compatible
2585with F9--MAC.
2586
2587\subsection{F9--MAC Functions}
2588A F9--MAC state is initialized with the following function:
2589\index{f9\_init()}
2590\begin{verbatim}
2591int f9_init(           f9_state *f9,
2592                            int  cipher,
2593            const unsigned char *key,
2594                  unsigned long  keylen);
2595\end{verbatim}
2596
2597This will initialize the F9--MAC state \textit{f9}, with the key specified in \textit{key} of length \textit{keylen} octets.  The cipher indicated
2598by the \textit{cipher} index can be either a 64 or 128--bit block cipher.  This will return \textbf{CRYPT\_OK} on success.
2599
2600To process data through F9--MAC use the following function:
2601\index{f9\_process()}
2602\begin{verbatim}
2603int f9_process(           f9_state *state,
2604               const unsigned char *in,
2605                     unsigned long  inlen);
2606\end{verbatim}
2607
2608This will add the message octets pointed to by \textit{in} of length \textit{inlen} to the F9--MAC state pointed to by \textit{state}.  Like the other MAC functions,
2609the granularity of the input is not important but the order is.  This will return \textbf{CRYPT\_OK} on success.
2610
2611To compute the MAC tag value use the following function:
2612
2613\index{f9\_done()}
2614\begin{verbatim}
2615int f9_done(     f9_state *state,
2616            unsigned char *out,
2617            unsigned long *outlen);
2618\end{verbatim}
2619
2620This will retrieve the F9--MAC tag from the state pointed to by \textit{state}, and store it in the array pointed to by \textit{out}.  The \textit{outlen} parameter
2621specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when the function returns.  This will return
2622\textbf{CRYPT\_OK} on success.
2623
2624Helper functions are provided to make parsing memory buffers and files easier.  The following functions are provided:
2625
2626\index{f9\_memory()}
2627\begin{verbatim}
2628int f9_memory(
2629                    int  cipher,
2630    const unsigned char *key, unsigned long  keylen,
2631    const unsigned char *in,  unsigned long  inlen,
2632          unsigned char *out, unsigned long *outlen);
2633\end{verbatim}
2634This will compute the F9--MAC of \textit{msglen} bytes of \textit{msg}, using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2635specified by the \textit{cipher}'th entry in the cipher\_descriptor table.  It will store the MAC in \textit{out} with the same rules as f9\_done().
2636
2637To F9--MAC a file use
2638\index{f9\_file()}
2639\begin{verbatim}
2640int f9_file(
2641                    int  cipher,
2642    const unsigned char *key,      unsigned long keylen,
2643             const char *filename,
2644          unsigned char *out,      unsigned long *outlen);
2645\end{verbatim}
2646
2647Which will F9--MAC the entire contents of the file specified by \textit{filename} using the key \textit{key} of length \textit{keylen} bytes, and the cipher
2648specified by the \textit{cipher}'th entry in the cipher\_descriptor table.  It will store the MAC in \textit{out} with the same rules as f9\_done().
2649
2650
2651To test f9--MAC for RFC 3566 compliance use the following function:
2652
2653\index{f9\_test()}
2654\begin{verbatim}
2655int f9_test(void);
2656\end{verbatim}
2657
2658This will return \textbf{CRYPT\_OK} on success.  This requires the AES or Rijndael descriptor be previously registered, otherwise, it will return
2659\textbf{CRYPT\_NOP}.
2660
2661\chapter{Pseudo-Random Number Generators}
2662\mysection{Core Functions}
2663The library provides an array of core functions for Pseudo-Random Number Generators (PRNGs) as well.  A cryptographic PRNG is
2664used to expand a shorter bit string into a longer bit string.  PRNGs are used wherever random data is required such as Public Key (PK)
2665key generation.  There is a universal structure called \textit{prng\_state}.  To initialize a PRNG call:
2666\index{PRNG start}
2667\begin{verbatim}
2668int XXX_start(prng_state *prng);
2669\end{verbatim}
2670
2671This will setup the PRNG for future use and not seed it.  In order for the PRNG to be cryptographically useful you must give it
2672entropy.  Ideally you'd have some OS level source to tap like in UNIX.  To add entropy to the PRNG call:
2673\index{PRNG add\_entropy}
2674\begin{verbatim}
2675int XXX_add_entropy(const unsigned char *in,
2676                          unsigned long  inlen,
2677                             prng_state *prng);
2678\end{verbatim}
2679Which returns {\bf CRYPT\_OK} if the entropy was accepted.  Once you think you have enough entropy you call another
2680function to put the entropy into action.
2681\index{PRNG ready}
2682\begin{verbatim}
2683int XXX_ready(prng_state *prng);
2684\end{verbatim}
2685
2686Which returns {\bf CRYPT\_OK} if it is ready.  Finally to actually read bytes call:
2687\index{PRNG read}
2688\begin{verbatim}
2689unsigned long XXX_read(unsigned char *out,
2690                       unsigned long  outlen,
2691                          prng_state *prng);
2692\end{verbatim}
2693
2694Which returns the number of bytes read from the PRNG.  When you are finished with a PRNG state you call
2695the following.
2696
2697\index{PRNG done}
2698\begin{verbatim}
2699void XXX_done(prng_state *prng);
2700\end{verbatim}
2701
2702This will terminate a PRNG state and free any memory (if any) allocated.  To export a PRNG state
2703so that you can later resume the PRNG call the following.
2704
2705\index{PRNG export}
2706\begin{verbatim}
2707int XXX_export(unsigned char *out,
2708               unsigned long *outlen,
2709                  prng_state *prng);
2710\end{verbatim}
2711
2712This will write a \textit{PRNG state} to the buffer \textit{out} of length \textit{outlen} bytes.  The idea of
2713the export is meant to be used as a \textit{seed file}.  That is, when the program starts up there will not likely
2714be that much entropy available.   To import a state to seed a PRNG call the following function.
2715
2716\index{PRNG import}
2717\begin{verbatim}
2718int XXX_import(const unsigned char *in,
2719                     unsigned long  inlen,
2720                        prng_state *prng);
2721\end{verbatim}
2722
2723This will call the start and add\_entropy functions of the given PRNG.  It will use the state in
2724\textit{in} of length \textit{inlen} as the initial seed.  You must pass the same seed length as was exported
2725by the corresponding export function.
2726
2727Note that importing a state will not \textit{resume} the PRNG from where it left off.  That is, if you export
2728a state, emit (say) 8 bytes and then import the previously exported state the next 8 bytes will not
2729specifically equal the 8 bytes you generated previously.
2730
2731When a program is first executed the normal course of operation is:
2732
2733\begin{enumerate}
2734   \item Gather entropy from your sources for a given period of time or number of events.
2735   \item Start, use your entropy via add\_entropy and ready the PRNG yourself.
2736\end{enumerate}
2737
2738When your program is finished you simply call the export function and save the state to a medium (disk,
2739flash memory, etc).  The next time your application starts up you can detect the state, feed it to the
2740import function and go on your way.  It is ideal that (as soon as possible) after start up you export a
2741fresh state.  This helps in the case that the program aborts or the machine is powered down without
2742being given a chance to exit properly.
2743
2744Note that even if you have a state to import it is important to add new entropy to the state.  However,
2745there is less pressure to do so.
2746
2747To test a PRNG for operational conformity call the following functions.
2748
2749\index{PRNG test}
2750\begin{verbatim}
2751int XXX_test(void);
2752\end{verbatim}
2753
2754This will return \textbf{CRYPT\_OK} if PRNG is operating properly.
2755
2756\subsection{Remarks}
2757
2758It is possible to be adding entropy and reading from a PRNG at the same time.  For example, if you first seed the PRNG
2759and call ready() you can now read from it.  You can also keep adding new entropy to it.  The new entropy will not be used
2760in the PRNG until ready() is called again.  This allows the PRNG to be used and re-seeded at the same time.  No real error
2761checking is guaranteed to see if the entropy is sufficient, or if the PRNG is even in a ready state before reading.
2762
2763\subsection{Example}
2764Below is a simple snippet to read 10 bytes from Yarrow.  It is important to note that this snippet is {\bf NOT} secure since
2765the entropy added is not random.
2766
2767\begin{verbatim}
2768#include <tomcrypt.h>
2769int main(void)
2770{
2771   prng_state prng;
2772   unsigned char buf[10];
2773   int err;
2774
2775   /* start it */
2776   if ((err = yarrow_start(&prng)) != CRYPT_OK) {
2777      printf("Start error: %s\n", error_to_string(err));
2778   }
2779   /* add entropy */
2780   if ((err = yarrow_add_entropy("hello world", 11, &prng))
2781       != CRYPT_OK) {
2782      printf("Add_entropy error: %s\n", error_to_string(err));
2783   }
2784   /* ready and read */
2785   if ((err = yarrow_ready(&prng)) != CRYPT_OK) {
2786      printf("Ready error: %s\n", error_to_string(err));
2787   }
2788   printf("Read %lu bytes from yarrow\n",
2789          yarrow_read(buf, sizeof(buf), &prng));
2790   return 0;
2791}
2792\end{verbatim}
2793
2794\mysection{PRNG Descriptors}
2795\index{PRNG Descriptor}
2796PRNGs have descriptors that allow plugin driven functions to be created using PRNGs. The plugin descriptors are stored in the structure \textit{prng\_descriptor}.  The
2797format of an element is:
2798\begin{verbatim}
2799struct _prng_descriptor {
2800    char *name;
2801    int  export_size;    /* size in bytes of exported state */
2802
2803    int (*start)      (prng_state *);
2804
2805    int (*add_entropy)(const unsigned char *, unsigned long,
2806                       prng_state *);
2807
2808    int (*ready)      (prng_state *);
2809
2810    unsigned long (*read)(unsigned char *, unsigned long len,
2811                          prng_state *);
2812
2813    void (*done)(prng_state *);
2814
2815    int (*export)(unsigned char *, unsigned long *, prng_state *);
2816
2817    int (*import)(const unsigned char *, unsigned long, prng_state *);
2818
2819    int (*test)(void);
2820};
2821\end{verbatim}
2822
2823To find a PRNG in the descriptor table the following function can be used:
2824\index{find\_prng()}
2825\begin{verbatim}
2826int find_prng(const char *name);
2827\end{verbatim}
2828This will search the PRNG descriptor table for the PRNG named \textit{name}.  It will return -1 if the PRNG is not found, otherwise, it returns
2829the index into the descriptor table.
2830
2831Just 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.
2832They are the following:
2833\index{register\_prng()} \index{unregister\_prng()}
2834\begin{verbatim}
2835int register_prng(const struct _prng_descriptor *prng);
2836int unregister_prng(const struct _prng_descriptor *prng);
2837\end{verbatim}
2838
2839The register function will register the PRNG, and return the index into the table where it was placed (or -1 for error).  It will avoid registering the same
2840descriptor twice, and will return the index of the current placement in the table if the caller attempts to register it more than once.  The unregister function
2841will return \textbf{CRYPT\_OK} if the PRNG was found and removed.  Otherwise, it returns \textbf{CRYPT\_ERROR}.
2842
2843\subsection{PRNGs Provided}
2844\begin{figure}[here]
2845\begin{center}
2846\begin{small}
2847\begin{tabular}{|c|c|l|}
2848\hline \textbf{Name} & \textbf{Descriptor} & \textbf{Usage} \\
2849\hline Yarrow & yarrow\_desc & Fast short-term PRNG \\
2850\hline Fortuna & fortuna\_desc & Fast long-term PRNG (recommended) \\
2851\hline RC4 & rc4\_desc & Stream Cipher \\
2852\hline SOBER-128 & sober128\_desc & Stream Cipher (also very fast PRNG) \\
2853\hline
2854\end{tabular}
2855\end{small}
2856\end{center}
2857\caption{List of Provided PRNGs}
2858\end{figure}
2859
2860\subsubsection{Yarrow}
2861Yarrow is fast PRNG meant to collect an unspecified amount of entropy from sources
2862(keyboard, mouse, interrupts, etc), and produce an unbounded string of random bytes.
2863
2864\textit{Note:} This PRNG is still secure for most tasks but is no longer recommended.  Users
2865should use Fortuna instead.
2866
2867\subsubsection{Fortuna}
2868
2869Fortuna is a fast attack tolerant and more thoroughly designed PRNG suitable for long term
2870usage.  It is faster than the default implementation of Yarrow\footnote{Yarrow has been implemented
2871to work with most cipher and hash combos based on which you have chosen to build into the library.} while
2872providing more security.
2873
2874Fortuna is slightly less flexible than Yarrow in the sense that it only works with the AES block cipher
2875and SHA--256 hash function.  Technically, Fortuna will work with any block cipher that accepts a 256--bit
2876key, and any hash that produces at least a 256--bit output.  However, to make the implementation simpler
2877it has been fixed to those choices.
2878
2879Fortuna is more secure than Yarrow in the sense that attackers who learn parts of the entropy being
2880added to the PRNG learn far less about the state than that of Yarrow.  Without getting into to many
2881details Fortuna has the ability to recover from state determination attacks where the attacker starts
2882to learn information from the PRNGs output about the internal state.  Yarrow on the other hand, cannot
2883recover from that problem until new entropy is added to the pool and put to use through the ready() function.
2884
2885\subsubsection{RC4}
2886
2887RC4 is an old stream cipher that can also double duty as a PRNG in a pinch.  You key RC4 by
2888calling add\_entropy(), and setup the key by calling ready().  You can only add up to 256 bytes via
2889add\_entropy().
2890
2891When you read from RC4, the output is XOR'ed against your buffer you provide.  In this manner, you can use rc4\_read()
2892as an encrypt (and decrypt) function.
2893
2894You really should not use RC4.  This is not because RC4 is weak, (though biases are known to exist) but simply due to
2895the fact that faster alternatives exist.
2896
2897\subsubsection{SOBER-128}
2898
2899SOBER--128 is a stream cipher designed by the QUALCOMM Australia team.  Like RC4, you key it by
2900calling add\_entropy().  There is no need to call ready() for this PRNG as it does not do anything.
2901
2902Note: this cipher has several oddities about how it operates.  The first call to add\_entropy() sets the cipher's key.
2903Every other time call to the add\_entropy() function sets the cipher's IV variable.  The IV mechanism allows you to
2904encrypt several messages with the same key, and not re--use the same key material.
2905
2906Unlike Yarrow and Fortuna, all of the entropy (and hence security) of this algorithm rests in the data
2907you pass it on the \textbf{first} call to add\_entropy().  All buffers sent to add\_entropy() must have a length
2908that is a multiple of four bytes.
2909
2910Like RC4, the output of SOBER--128 is XOR'ed against the buffer you provide it.  In this manner, you can use
2911sober128\_read() as an encrypt (and decrypt) function.
2912
2913Since SOBER-128 has a fixed keying scheme, and is very fast (faster than RC4) the ideal usage of SOBER-128 is to
2914key it from the output of Fortuna (or Yarrow), and use it to encrypt messages.  It is also ideal for
2915simulations which need a high quality (and fast) stream of bytes.
2916
2917\subsubsection{Example Usage}
2918\begin{small}
2919\begin{verbatim}
2920#include <tomcrypt.h>
2921int main(void)
2922{
2923   prng_state prng;
2924   unsigned char buf[32];
2925   int err;
2926
2927   if ((err = rc4_start(&prng)) != CRYPT_OK) {
2928      printf("RC4 init error: %s\n", error_to_string(err));
2929      exit(-1);
2930   }
2931
2932   /* use "key" as the key */
2933   if ((err = rc4_add_entropy("key", 3, &prng)) != CRYPT_OK) {
2934      printf("RC4 add entropy error: %s\n", error_to_string(err));
2935      exit(-1);
2936   }
2937
2938   /* setup RC4 for use */
2939   if ((err = rc4_ready(&prng)) != CRYPT_OK) {
2940      printf("RC4 ready error: %s\n", error_to_string(err));
2941      exit(-1);
2942   }
2943
2944   /* encrypt buffer */
2945   strcpy(buf,"hello world");
2946   if (rc4_read(buf, 11, &prng) != 11) {
2947      printf("RC4 read error\n");
2948      exit(-1);
2949   }
2950   return 0;
2951}
2952\end{verbatim}
2953\end{small}
2954To decrypt you have to do the exact same steps.
2955
2956\mysection{The Secure RNG}
2957\index{Secure RNG}
2958An RNG is related to a PRNG in many ways, except that it does not expand a smaller seed to get the data.  They generate their random bits
2959by performing some computation on fresh input bits.  Possibly the hardest thing to get correctly in a cryptosystem is the
2960PRNG.  Computers are deterministic that try hard not to stray from pre--determined paths.  This makes gathering entropy needed to seed a PRNG
2961a hard task.
2962
2963There is one small function that may help on certain platforms:
2964\index{rng\_get\_bytes()}
2965\begin{verbatim}
2966unsigned long rng_get_bytes(
2967    unsigned char *buf,
2968    unsigned long  len,
2969    void         (*callback)(void));
2970\end{verbatim}
2971
2972Which will try one of three methods of getting random data.  The first is to open the popular \textit{/dev/random} device which
2973on most *NIX platforms provides cryptographic random bits\footnote{This device is available in Windows through the Cygwin compiler suite.  It emulates \textit{/dev/random} via the Microsoft CSP.}.
2974The second method is to try the Microsoft Cryptographic Service Provider, and read the RNG.  The third method is an ANSI C
2975clock drift method that is also somewhat popular but gives bits of lower entropy.  The \textit{callback} parameter is a pointer to a function that returns void.  It is
2976used 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 roughly three
2977bytes a second.  The callback pointer may be set to {\bf NULL} to avoid using it if you do not want to.  The function returns the number of bytes actually read from
2978any RNG source.  There is a function to help setup a PRNG as well:
2979\index{rng\_make\_prng()}
2980\begin{verbatim}
2981int rng_make_prng(       int  bits,
2982                         int  wprng,
2983                  prng_state *prng,
2984                       void (*callback)(void));
2985\end{verbatim}
2986This will try to initialize the prng with a state of at least \textit{bits} of entropy.  The \textit{callback} parameter works much like
2987the callback in \textit{rng\_get\_bytes()}.  It is highly recommended that you use this function to setup your PRNGs unless you have a
2988platform where the RNG does not work well.  Example usage of this function is given below:
2989
2990\begin{small}
2991\begin{verbatim}
2992#include <tomcrypt.h>
2993int main(void)
2994{
2995   ecc_key mykey;
2996   prng_state prng;
2997   int err;
2998
2999   /* register yarrow */
3000   if (register_prng(&yarrow_desc) == -1) {
3001      printf("Error registering Yarrow\n");
3002      return -1;
3003   }
3004
3005   /* setup the PRNG */
3006   if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL))
3007       != CRYPT_OK) {
3008      printf("Error setting up PRNG, %s\n", error_to_string(err));
3009      return -1;
3010   }
3011
3012   /* make a 192-bit ECC key */
3013   if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey))
3014       != CRYPT_OK) {
3015      printf("Error making key: %s\n", error_to_string(err));
3016      return -1;
3017   }
3018   return 0;
3019}
3020\end{verbatim}
3021\end{small}
3022
3023\subsection{The Secure PRNG Interface}
3024It is possible to access the secure RNG through the PRNG interface, and in turn use it within dependent functions such
3025as the PK API.  This simplifies the cryptosystem on platforms where the secure RNG is fast.  The secure PRNG never
3026requires to be started, that is you need not call the start, add\_entropy, or ready functions.  For example, consider
3027the previous example using this PRNG.
3028
3029\begin{small}
3030\begin{verbatim}
3031#include <tomcrypt.h>
3032int main(void)
3033{
3034   ecc_key mykey;
3035   int err;
3036
3037   /* register SPRNG */
3038   if (register_prng(&sprng_desc) == -1) {
3039      printf("Error registering SPRNG\n");
3040      return -1;
3041   }
3042
3043   /* make a 192-bit ECC key */
3044   if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey))
3045       != CRYPT_OK) {
3046      printf("Error making key: %s\n", error_to_string(err));
3047      return -1;
3048   }
3049   return 0;
3050}
3051\end{verbatim}
3052\end{small}
3053
3054\chapter{RSA Public Key Cryptography}
3055
3056\mysection{Introduction}
3057RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography.  In the specifications are
3058padding algorithms for encryption and signatures.  The standard includes the \textit{v1.5} and \textit{v2.1} algorithms.
3059To simplify matters a little the v2.1 encryption and signature padding algorithms are called OAEP and PSS respectively.
3060
3061\mysection{PKCS \#1 Padding}
3062PKCS \#1 v1.5 padding is so simple that both signature and encryption padding are performed by the same function.  Note: the
3063signature padding does \textbf{not} include the ASN.1 padding required.  That is performed by the rsa\_sign\_hash\_ex() function
3064documented later on in this chapter.
3065
3066\subsection{PKCS \#1 v1.5 Encoding}
3067The following function performs PKCS \#1 v1.5 padding:
3068\index{pkcs\_1\_v1\_5\_encode()}
3069\begin{verbatim}
3070int pkcs_1_v1_5_encode(
3071    const unsigned char *msg,
3072          unsigned long  msglen,
3073                    int  block_type,
3074          unsigned long  modulus_bitlen,
3075             prng_state *prng,
3076                    int  prng_idx,
3077          unsigned char *out,
3078          unsigned long *outlen);
3079\end{verbatim}
3080
3081This will encode the message pointed to by \textit{msg} of length \textit{msglen} octets.  The \textit{block\_type} parameter must be set to
3082\textbf{LTC\_PKCS\_1\_EME} to perform encryption padding.  It must be set to \textbf{LTC\_PKCS\_1\_EMSA} to perform signature padding.  The \textit{modulus\_bitlen}
3083parameter indicates the length of the modulus in bits.  The padded data is stored in \textit{out} with a length of \textit{outlen} octets.  The output will not be
3084longer than the modulus which helps allocate the correct output buffer size.
3085
3086Only encryption padding requires a PRNG.  When performing signature padding the \textit{prng\_idx} parameter may be left to zero as it is not checked for validity.
3087
3088\subsection{PKCS \#1 v1.5 Decoding}
3089The following function performs PKCS \#1 v1.5 de--padding:
3090\index{pkcs\_1\_v1\_5\_decode()}
3091\begin{verbatim}
3092int pkcs_1_v1_5_decode(
3093    const unsigned char *msg,
3094          unsigned long  msglen,
3095                    int  block_type,
3096          unsigned long  modulus_bitlen,
3097          unsigned char *out,
3098          unsigned long *outlen,
3099                    int *is_valid);
3100\end{verbatim}
3101\index{LTC\_PKCS\_1\_EME} \index{LTC\_PKCS\_1\_EMSA}
3102This will remove the PKCS padding data pointed to by \textit{msg} of length \textit{msglen}.  The decoded data is stored in \textit{out} of length
3103\textit{outlen}.  If the padding is valid, a 1 is stored in \textit{is\_valid}, otherwise, a 0 is stored.  The \textit{block\_type} parameter must be set to either
3104\textbf{LTC\_PKCS\_1\_EME} or \textbf{LTC\_PKCS\_1\_EMSA} depending on whether encryption or signature padding is being removed.
3105
3106\mysection{PKCS \#1 v2.1 Encryption}
3107PKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation.  As far as this portion of
3108the library is concerned we are only dealing with th OAEP padding of the message.
3109
3110\subsection{OAEP Encoding}
3111
3112The following function performs PKCS \#1 v2.1 encryption padding:
3113
3114\index{pkcs\_1\_oaep\_encode()}
3115\begin{alltt}
3116int pkcs_1_oaep_encode(
3117    const unsigned char *msg,
3118          unsigned long  msglen,
3119    const unsigned char *lparam,
3120          unsigned long  lparamlen,
3121          unsigned long  modulus_bitlen,
3122             prng_state *prng,
3123                    int  prng_idx,
3124                    int  hash_idx,
3125          unsigned char *out,
3126          unsigned long *outlen);
3127\end{alltt}
3128
3129This accepts \textit{msg} as input of length \textit{msglen} which will be OAEP padded.  The \textit{lparam} variable is an additional system specific
3130tag that can be applied to the encoding.  This is useful to identify which system encoded the message.  If no variance is desired then
3131\textit{lparam} can be set to \textbf{NULL}.
3132
3133OAEP encoding requires the length of the modulus in bits in order to calculate the size of the output.  This is passed as the parameter
3134\textit{modulus\_bitlen}.  \textit{hash\_idx} is the index into the hash descriptor table of the hash desired.  PKCS \#1 allows any hash to be
3135used 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
3136 sized input message.  \textit{prng\_idx} and \textit{prng} are the random number generator arguments required to randomize the padding process.
3137The padded message is stored in \textit{out} along with the length in \textit{outlen}.
3138
3139If $h$ is the length of the hash and $m$ the length of the modulus (both in octets) then the maximum payload for \textit{msg} is
3140$m - 2h - 2$.  For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes.
3141
3142Note that when the message is padded it still has not been RSA encrypted.  You must pass the output of this function to
3143rsa\_exptmod() to encrypt it.
3144
3145\subsection{OAEP Decoding}
3146
3147\index{pkcs\_1\_oaep\_decode()}
3148\begin{alltt}
3149int pkcs_1_oaep_decode(
3150    const unsigned char *msg,
3151          unsigned long  msglen,
3152    const unsigned char *lparam,
3153          unsigned long  lparamlen,
3154          unsigned long  modulus_bitlen,
3155                    int  hash_idx,
3156          unsigned char *out,
3157          unsigned long *outlen,
3158                    int *res);
3159\end{alltt}
3160
3161This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder.  \textit{msg} is the
3162output of pkcs\_1\_oaep\_encode() of length \textit{msglen}.  \textit{lparam} is the same system variable passed to the OAEP encoder.  If it does not
3163match what was used during encoding this function will not decode the packet.  \textit{modulus\_bitlen} is the size of the RSA modulus in bits
3164and must match what was used during encoding.  Similarly the \textit{hash\_idx} index into the hash descriptor table must match what was used
3165during encoding.
3166
3167If the function succeeds it decodes the OAEP encoded message into \textit{out} of length \textit{outlen} and stores a
3168$1$ in \textit{res}.  If the packet is invalid it stores $0$ in \textit{res} and if the function fails for another reason
3169it returns an error code.
3170
3171\mysection{PKCS \#1 Digital Signatures}
3172
3173\subsection{PSS Encoding}
3174PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed.
3175
3176\index{pkcs\_1\_pss\_encode()}
3177\begin{alltt}
3178int pkcs_1_pss_encode(
3179    const unsigned char *msghash,
3180          unsigned long  msghashlen,
3181          unsigned long  saltlen,
3182             prng_state *prng,
3183                    int  prng_idx,
3184                    int  hash_idx,
3185          unsigned long  modulus_bitlen,
3186          unsigned char *out,
3187          unsigned long *outlen);
3188\end{alltt}
3189
3190This function assumes the message to be PSS encoded has previously been hashed.  The input hash \textit{msghash} is of length
3191\textit{msghashlen}.  PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process.
3192\textit{hash\_idx} is the index into the hash descriptor table of the hash to use.  \textit{prng\_idx} and \textit{prng} are the random
3193number generator information required for the salt.
3194
3195Similar to OAEP encoding \textit{modulus\_bitlen} is the size of the RSA modulus (in bits).  It limits the size of the salt.  If $m$ is the length
3196of the modulus $h$ the length of the hash output (in octets) then there can be $m - h - 2$ bytes of salt.
3197
3198This function does not actually sign the data it merely pads the hash of a message so that it can be processed by rsa\_exptmod().
3199
3200\subsection{PSS Decoding}
3201
3202To decode a PSS encoded signature block you have to use the following.
3203
3204\index{pkcs\_1\_pss\_decode()}
3205\begin{alltt}
3206int pkcs_1_pss_decode(
3207    const unsigned char *msghash,
3208          unsigned long  msghashlen,
3209    const unsigned char *sig,
3210          unsigned long  siglen,
3211          unsigned long  saltlen,
3212                    int  hash_idx,
3213          unsigned long  modulus_bitlen,
3214                    int *res);
3215\end{alltt}
3216This will decode the PSS encoded message in \textit{sig} of length \textit{siglen} and compare it to values in \textit{msghash} of length
3217\textit{msghashlen}.  If the block is a valid PSS block and the decoded hash equals the hash supplied \textit{res} is set to non--zero.  Otherwise,
3218it is set to zero.  The rest of the parameters are as in the PSS encode call.
3219
3220It's important to use the same \textit{saltlen} and hash for both encoding and decoding as otherwise the procedure will not work.
3221
3222\mysection{RSA Key Operations}
3223\subsection{Background}
3224
3225RSA is a public key algorithm that is based on the inability to find the \textit{e-th} root modulo a composite of unknown
3226factorization.  Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are
3227not strictly equivalent.
3228
3229The system begins with with two primes $p$ and $q$ and their product $N = pq$.  The order or \textit{Euler totient} of the
3230multiplicative sub-group formed modulo $N$ is given as $\phi(N) = (p - 1)(q - 1)$ which can be reduced to
3231$\mbox{lcm}(p - 1, q - 1)$.  The public key consists of the composite $N$ and some integer $e$ such that
3232$\mbox{gcd}(e, \phi(N)) = 1$.  The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$
3233often simply denoted as $de \equiv 1\mbox{ }(\mbox{mod }\phi(N))$.
3234
3235A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that
3236$1 < M < N-2$ and computes the ciphertext $C = M^e\mbox{ }(\mbox{mod }N)$.  Since finding the inverse exponent $d$
3237given only $N$ and $e$ appears to be intractable only the owner of the private key can decrypt the ciphertext and compute
3238$C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$.  Similarly the owner of the private key
3239can sign a message by \textit{decrypting} it.  Others can verify it by \textit{encrypting} it.
3240
3241Currently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other.
3242Ideally $e$ should be larger than $100$ to prevent direct analysis.  For example, if $e$ is three and you do not pad
3243the plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial.
3244The most often suggested value for $e$ is $65537$ since it is large enough to make such attacks impossible and also well
3245designed for fast exponentiation (requires 16 squarings and one multiplication).
3246
3247It is important to pad the input to RSA since it has particular mathematical structure.  For instance
3248$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
3249to have a forged signature for.  Simply get the signatures for $M_1$ and $M_2$ on their own and multiply the result
3250together.  Similar tricks can be used to deduce plaintexts from ciphertexts.  It is important not only to sign
3251the hash of documents only but also to pad the inputs with data to remove such structure.
3252
3253\subsection{RSA Key Generation}
3254
3255For RSA routines a single \textit{rsa\_key} structure is used.  To make a new RSA key call:
3256\index{rsa\_make\_key()}
3257\begin{verbatim}
3258int rsa_make_key(prng_state *prng,
3259                        int  wprng,
3260                        int  size,
3261                       long  e,
3262                    rsa_key *key);
3263\end{verbatim}
3264
3265Where \textit{wprng} is the index into the PRNG descriptor array.  The \textit{size} parameter is the size in bytes of the RSA modulus desired.
3266The \textit{e} parameter is the encryption exponent desired, typical values are 3, 17, 257 and 65537.  Stick with 65537 since it is big enough to prevent
3267trivial math attacks, and not super slow.  The \textit{key} parameter is where the constructed key is placed.  All keys must be at
3268least 128 bytes, and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}).
3269
3270\index{rsa\_free()}
3271Note: the \textit{rsa\_make\_key()} function allocates memory at run--time when you make the key.  Make sure to call
3272\textit{rsa\_free()} (see below) when you are finished with the key.  If \textit{rsa\_make\_key()} fails it will automatically
3273free the memory allocated.
3274
3275\index{PK\_PRIVATE} \index{PK\_PUBLIC}
3276There are two types of RSA keys.  The types are {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}.  The first type is a private
3277RSA key which includes the CRT parameters\footnote{As of v0.99 the PK\_PRIVATE\_OPTIMIZED type has been deprecated, and has been replaced by the
3278PK\_PRIVATE type.} in the form of a RSAPrivateKey (PKCS \#1 compliant).  The second type, is a public RSA key which only includes the modulus and public exponent.
3279It takes the form of a RSAPublicKey (PKCS \#1 compliant).
3280
3281\subsection{RSA Exponentiation}
3282To do raw work with the RSA function, that is without padding, use the following function:
3283\index{rsa\_exptmod()}
3284\begin{verbatim}
3285int rsa_exptmod(const unsigned char *in,
3286                      unsigned long  inlen,
3287                      unsigned char *out,
3288                      unsigned long *outlen,
3289                                int  which,
3290                            rsa_key *key);
3291\end{verbatim}
3292This will load the bignum from \textit{in} as a big endian integer in the format PKCS \#1 specifies, raises it to either \textit{e} or \textit{d} and stores the result
3293in \textit{out} and the size of the result in \textit{outlen}. \textit{which} is set to {\bf PK\_PUBLIC} to use \textit{e}
3294(i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use \textit{d} as the exponent (i.e. for decrypting/signing).
3295
3296Note: the output of this function is zero--padded as per PKCS \#1 specification.  This allows this routine to work with PKCS \#1 padding functions properly.
3297
3298\mysection{RSA Key Encryption}
3299Normally RSA is used to encrypt short symmetric keys which are then used in block ciphers to encrypt a message.
3300To facilitate encrypting short keys the following functions have been provided.
3301
3302\index{rsa\_encrypt\_key()}
3303\begin{verbatim}
3304int rsa_encrypt_key(
3305    const unsigned char *in,
3306          unsigned long  inlen,
3307          unsigned char *out,
3308          unsigned long *outlen,
3309    const unsigned char *lparam,
3310          unsigned long  lparamlen,
3311             prng_state *prng,
3312                    int  prng_idx,
3313                    int  hash_idx,
3314                rsa_key *key);
3315\end{verbatim}
3316This function will OAEP pad \textit{in} of length \textit{inlen} bytes, RSA encrypt it, and store the ciphertext
3317in \textit{out} of length \textit{outlen} octets.  The \textit{lparam} and \textit{lparamlen} are the same parameters you would pass
3318to \index{pkcs\_1\_oaep\_encode()} pkcs\_1\_oaep\_encode().
3319
3320\subsection{Extended Encryption}
3321As of v1.15, the library supports both v1.5 and v2.1 PKCS \#1 style paddings in these higher level functions.  The following is the extended
3322encryption function:
3323
3324\index{rsa\_encrypt\_key\_ex()}
3325\begin{verbatim}
3326int rsa_encrypt_key_ex(
3327    const unsigned char *in,
3328          unsigned long  inlen,
3329          unsigned char *out,
3330          unsigned long *outlen,
3331    const unsigned char *lparam,
3332          unsigned long  lparamlen,
3333             prng_state *prng,
3334                    int  prng_idx,
3335                    int  hash_idx,
3336                    int  padding,
3337                rsa_key *key);
3338\end{verbatim}
3339
3340\index{LTC\_PKCS\_1\_OAEP} \index{LTC\_PKCS\_1\_V1\_5}
3341The parameters are all the same as for rsa\_encrypt\_key() except for the addition of the \textit{padding} parameter.  It must be set to
3342\textbf{LTC\_PKCS\_1\_V1\_5} to perform v1.5 encryption, or set to \textbf{LTC\_PKCS\_1\_OAEP} to perform v2.1 encryption.
3343
3344When performing v1.5 encryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively).
3345
3346\mysection{RSA Key Decryption}
3347\index{rsa\_decrypt\_key()}
3348\begin{verbatim}
3349int rsa_decrypt_key(
3350    const unsigned char *in,
3351          unsigned long  inlen,
3352          unsigned char *out,
3353          unsigned long *outlen,
3354    const unsigned char *lparam,
3355          unsigned long  lparamlen,
3356                    int  hash_idx,
3357                    int *stat,
3358                rsa_key *key);
3359\end{verbatim}
3360This function will RSA decrypt \textit{in} of length \textit{inlen} then OAEP de-pad the resulting data and store it in
3361\textit{out} of length \textit{outlen}.  The \textit{lparam} and \textit{lparamlen} are the same parameters you would pass
3362to pkcs\_1\_oaep\_decode().
3363
3364If the RSA decrypted data is not a valid OAEP packet then \textit{stat} is set to $0$.  Otherwise, it is set to $1$.
3365
3366\subsection{Extended Decryption}
3367As of v1.15, the library supports both v1.5 and v2.1 PKCS \#1 style paddings in these higher level functions.  The following is the extended
3368decryption function:
3369
3370\index{rsa\_decrypt\_key\_ex()}
3371\begin{verbatim}
3372int rsa_decrypt_key_ex(
3373    const unsigned char *in,
3374          unsigned long  inlen,
3375          unsigned char *out,
3376          unsigned long *outlen,
3377    const unsigned char *lparam,
3378          unsigned long  lparamlen,
3379                    int  hash_idx,
3380                    int  padding,
3381                    int *stat,
3382                rsa_key *key);
3383\end{verbatim}
3384
3385Similar to the extended encryption, the new parameter \textit{padding} indicates which version of the PKCS \#1 standard to use.
3386It must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform v1.5 decryption, or set to \textbf{LTC\_PKCS\_1\_OAEP} to perform v2.1 decryption.
3387
3388When performing v1.5 decryption, the hash and lparam parameters are totally ignored and can be set to \textbf{NULL} or zero (respectively).
3389
3390
3391\mysection{RSA Signature Generation}
3392Similar to RSA key encryption RSA is also used to \textit{digitally sign} message digests (hashes).  To facilitate this
3393process the following functions have been provided.
3394
3395\index{rsa\_sign\_hash()}
3396\begin{verbatim}
3397int rsa_sign_hash(const unsigned char *in,
3398                        unsigned long  inlen,
3399                        unsigned char *out,
3400                        unsigned long *outlen,
3401                           prng_state *prng,
3402                                  int  prng_idx,
3403                                  int  hash_idx,
3404                        unsigned long  saltlen,
3405                              rsa_key *key);
3406\end{verbatim}
3407
3408This will PSS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets.  Next, the PSS encoded hash will be RSA
3409\textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets.
3410
3411The \textit{hash\_idx} parameter indicates which hash will be used to create the PSS encoding.  It should be the same as the hash used to
3412hash the message being signed.  The \textit{saltlen} parameter indicates the length of the desired salt, and should typically be small.  A good
3413default value is between 8 and 16 octets.  Strictly, it must be small than $modulus\_len - hLen - 2$ where \textit{modulus\_len} is the size of
3414the RSA modulus (in octets), and \textit{hLen} is the length of the message digest produced by the chosen hash.
3415
3416\subsection{Extended Signatures}
3417
3418As of v1.15, the library supports both v1.5 and v2.1 signatures.  The extended signature generation function has the following prototype:
3419
3420\index{rsa\_sign\_hash\_ex()}
3421\begin{verbatim}
3422int rsa_sign_hash_ex(
3423    const unsigned char *in,
3424          unsigned long  inlen,
3425          unsigned char *out,
3426          unsigned long *outlen,
3427                    int  padding,
3428          prng_state    *prng,
3429                    int  prng_idx,
3430                    int  hash_idx,
3431          unsigned long  saltlen,
3432                rsa_key *key);
3433\end{verbatim}
3434
3435This will PKCS encode the message digest pointed to by \textit{in} of length \textit{inlen} octets.  Next, the PKCS encoded hash will be RSA
3436\textit{signed} and the output stored in the buffer pointed to by \textit{out} of length \textit{outlen} octets.  The \textit{padding} parameter
3437must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to produce a v1.5 signature, otherwise, it must be set to \textbf{LTC\_PKCS\_1\_PSS} to produce a
3438v2.1 signature.
3439
3440When performing a v1.5 signature the \textit{prng}, \textit{prng\_idx}, and \textit{hash\_idx} parameters are not checked and can be left to any
3441values such as $\lbrace$\textbf{NULL}, 0, 0$\rbrace$.
3442
3443\mysection{RSA Signature Verification}
3444\index{rsa\_verify\_hash()}
3445\begin{verbatim}
3446int rsa_verify_hash(const unsigned char *sig,
3447                          unsigned long  siglen,
3448                    const unsigned char *msghash,
3449                          unsigned long  msghashlen,
3450                                    int  hash_idx,
3451                          unsigned long  saltlen,
3452                                    int *stat,
3453                                rsa_key *key);
3454\end{verbatim}
3455
3456This will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets.  Next, the RSA decoded data is PSS decoded
3457and the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets.
3458
3459If the RSA decoded data is not a valid PSS message, or if the PSS decoded hash does not match the \textit{msghash}
3460value, \textit{res} is set to $0$.  Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$.
3461
3462\subsection{Extended Verification}
3463
3464As of v1.15, the library supports both v1.5 and v2.1 signature verification.  The extended signature verification function has the following prototype:
3465
3466\index{rsa\_verify\_hash\_ex()}
3467\begin{verbatim}
3468int rsa_verify_hash_ex(
3469    const unsigned char *sig,
3470          unsigned long  siglen,
3471    const unsigned char *hash,
3472          unsigned long  hashlen,
3473                    int  padding,
3474                    int  hash_idx,
3475          unsigned long  saltlen,
3476                    int *stat,
3477                rsa_key *key);
3478\end{verbatim}
3479
3480This will RSA \textit{verify} the signature pointed to by \textit{sig} of length \textit{siglen} octets.  Next, the RSA decoded data is PKCS decoded
3481and the extracted hash is compared against the message digest pointed to by \textit{msghash} of length \textit{msghashlen} octets.
3482
3483If the RSA decoded data is not a valid PSS message, or if the PKCS decoded hash does not match the \textit{msghash}
3484value, \textit{res} is set to $0$.  Otherwise, if the function succeeds, and signature is valid \textit{res} is set to $1$.
3485
3486The \textit{padding} parameter must be set to \textbf{LTC\_PKCS\_1\_V1\_5} to perform a v1.5 verification.  Otherwise, it must be set to
3487\textbf{LTC\_PKCS\_1\_PSS} to perform a v2.1 verification.  When performing a v1.5 verification the \textit{hash\_idx} parameter is ignored.
3488
3489\mysection{RSA Encryption Example}
3490\begin{small}
3491\begin{verbatim}
3492#include <tomcrypt.h>
3493int main(void)
3494{
3495   int           err, hash_idx, prng_idx, res;
3496   unsigned long l1, l2;
3497   unsigned char pt[16], pt2[16], out[1024];
3498   rsa_key       key;
3499
3500   /* register prng/hash */
3501   if (register_prng(&sprng_desc) == -1) {
3502      printf("Error registering sprng");
3503      return EXIT_FAILURE;
3504   }
3505
3506   /* register a math library (in this case TomsFastMath)
3507   ltc_mp = tfm_desc;
3508
3509   if (register_hash(&sha1_desc) == -1) {
3510      printf("Error registering sha1");
3511      return EXIT_FAILURE;
3512   }
3513   hash_idx = find_hash("sha1");
3514   prng_idx = find_prng("sprng");
3515
3516   /* make an RSA-1024 key */
3517   if ((err = rsa_make_key(NULL,     /* PRNG state */
3518                           prng_idx, /* PRNG idx */
3519                           1024/8,   /* 1024-bit key */
3520                           65537,    /* we like e=65537 */
3521                           &key)     /* where to store the key */
3522       ) != CRYPT_OK) {
3523       printf("rsa_make_key %s", error_to_string(err));
3524       return EXIT_FAILURE;
3525   }
3526
3527   /* fill in pt[] with a key we want to send ... */
3528   l1 = sizeof(out);
3529   if ((err = rsa_encrypt_key(pt, /* data we wish to encrypt */
3530                              16, /* data is 16 bytes long */
3531                             out, /* where to store ciphertext */
3532                             &l1, /* length of ciphertext */
3533                       "TestApp", /* our lparam for this program */
3534                               7, /* lparam is 7 bytes long */
3535                            NULL, /* PRNG state */
3536                        prng_idx, /* prng idx */
3537                        hash_idx, /* hash idx */
3538                            &key) /* our RSA key */
3539       ) != CRYPT_OK) {
3540       printf("rsa_encrypt_key %s", error_to_string(err));
3541       return EXIT_FAILURE;
3542   }
3543
3544   /* now let's decrypt the encrypted key */
3545   l2 = sizeof(pt2);
3546   if ((err = rsa_decrypt_key(out, /* encrypted data */
3547                               l1, /* length of ciphertext */
3548                              pt2, /* where to put plaintext */
3549                              &l2, /* plaintext length */
3550                        "TestApp", /* lparam for this program */
3551                                7, /* lparam is 7 bytes long */
3552                         hash_idx, /* hash idx */
3553                             &res, /* validity of data */
3554                             &key) /* our RSA key */
3555        ) != CRYPT_OK) {
3556       printf("rsa_decrypt_key %s", error_to_string(err));
3557       return EXIT_FAILURE;
3558   }
3559   /* if all went well pt == pt2, l2 == 16, res == 1 */
3560}
3561\end{verbatim}
3562\end{small}
3563
3564\mysection{RSA Key Format}
3565
3566The RSA key format adopted for exporting and importing keys is the PKCS \#1 format defined by the ASN.1 constructs known as
3567RSAPublicKey and RSAPrivateKey.  Additionally, the OpenSSL key format is supported by the import function only.
3568
3569\subsection{RSA Key Export}
3570To export a RSA key use the following function.
3571
3572\index{rsa\_export()}
3573\begin{verbatim}
3574int rsa_export(unsigned char *out,
3575               unsigned long *outlen,
3576                         int  type,
3577                     rsa_key *key);
3578\end{verbatim}
3579This will export the RSA key in either a RSAPublicKey or RSAPrivateKey (PKCS \#1 types) depending on the value of \textit{type}.  When it is
3580set to \textbf{PK\_PRIVATE} the export format will be RSAPrivateKey and otherwise it will be RSAPublicKey.
3581
3582\subsection{RSA Key Import}
3583To import a RSA key use the following function.
3584
3585\index{rsa\_import()}
3586\begin{verbatim}
3587int rsa_import(const unsigned char *in,
3588                     unsigned long  inlen,
3589                           rsa_key *key);
3590\end{verbatim}
3591
3592This will import the key stored in \textit{inlen} and import it to \textit{key}.  If the function fails it will automatically free any allocated memory.  This
3593function can import both RSAPublicKey and RSAPrivateKey formats.
3594
3595As of v1.06 this function can also import OpenSSL DER formatted public RSA keys.  They are essentially encapsulated RSAPublicKeys.  LibTomCrypt will
3596import the key, strip off the additional data (it's the preferred hash) and fill in the rsa\_key structure as if it were a native RSAPublicKey.  Note that
3597there is no function provided to export in this format.
3598
3599\chapter{Elliptic Curve Cryptography}
3600
3601\mysection{Background}
3602The library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the
3603Diffie-Hellman routines in the previous chapter.  Elliptic curves (of certain forms) have the benefit that they are harder
3604to attack (no sub-exponential attacks exist unlike normal DH crypto) in fact the fastest attack requires the square root
3605of the order of the base point in time.  That means if you use a base point of order $2^{192}$ (which would represent a
3606192-bit key) then the work factor is $2^{96}$ in order to find the secret key.
3607
3608The curves in this library are taken from the following website:
3609\begin{verbatim}
3610http://csrc.nist.gov/cryptval/dss.htm
3611\end{verbatim}
3612
3613As of v1.15 three new curves from the SECG standards are also included they are the secp112r1, secp128r1, and secp160r1 curves.  These curves were added to
3614support smaller devices which do not need as large keys for security.
3615
3616They are all curves over the integers modulo a prime.  The curves have the basic equation that is:
3617\begin{equation}
3618y^2 = x^3 - 3x + b\mbox{ }(\mbox{mod }p)
3619\end{equation}
3620
3621The variable $b$ is chosen such that the number of points is nearly maximal.  In fact the order of the base points $\beta$
3622provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$.  The curves
3623range in order from $\approx 2^{112}$ points to $\approx 2^{521}$.  According to the source document any key size greater
3624than or equal to 256-bits is sufficient for long term security.
3625
3626\mysection{Fixed Point Optimizations}
3627\index{Fixed Point ECC}
3628\index{MECC\_FP}
3629As of v1.12 of LibTomCrypt, support for Fixed Point ECC point multiplication has been added.  It is a generic optimization that is
3630supported by any conforming math plugin.  It is enabled by defining \textbf{MECC\_FP} during the build, such as
3631
3632\begin{verbatim}
3633CFLAGS="-DTFM_DESC -DMECC_FP" make
3634\end{verbatim}
3635
3636which will build LTC using the TFM math library and enabling this new feature.  The feature is not enabled by default as it is \textbf{NOT} thread
3637safe (by default).  It supports the LTC locking macros (such as by enabling LTC\_PTHREAD), but by default is not locked.
3638
3639\index{FP\_ENTRIES}
3640The optimization works by using a Fixed Point multiplier on any base point you use twice or more in a short period of time.  It has a limited size
3641cache (of FP\_ENTRIES entries) which it uses to hold recent bases passed to ltc\_ecc\_mulmod().  Any base detected to be used twice is sent through the
3642pre--computation phase, and then the fixed point algorithm can be used.  For example, if you use a NIST base point twice in a row, the 2$^{nd}$ and
3643all subsequent point multiplications with that point will use the faster algorithm.
3644
3645\index{FP\_LUT}
3646The optimization uses a window on the multiplicand of FP\_LUT bits (default: 8, min: 2, max: 12), and this controls the memory/time trade-off. The larger the
3647value the faster the algorithm will be but the more memory it will take.  The memory usage is $3 \cdot 2^{FP\_LUT}$ integers which by default
3648with TFM amounts to about 400kB of memory.  Tuning TFM (by changing FP\_SIZE) can decrease the usage by a fair amount.  Memory is only used by a cache entry
3649if it is active.  Both FP\_ENTRIES and FP\_LUT are definable on the command line if you wish to override them. For instance,
3650
3651\begin{verbatim}
3652CFLAGS="-DTFM_DESC -DMECC_FP -DFP_ENTRIES=8 -DFP_LUT=6" make
3653\end{verbatim}
3654
3655\begin{flushleft}
3656\index{FP\_SIZE} \index{TFM} \index{tfm.h}
3657would define a window of 6 bits and limit the cache to 8 entries.  Generally, it is better to first tune TFM by adjusting FP\_SIZE (from tfm.h).  It defaults
3658to 4096 bits (512 bytes) which is way more than what is required by ECC.  At most, you need 1152 bits to accommodate ECC--521.  If you're only using (say)
3659ECC--256 you will only need 576 bits, which would reduce the memory usage by 700\%.
3660\end{flushleft}
3661
3662\mysection{Key Format}
3663LibTomCrypt uses a unique format for ECC public and private keys.  While ANSI X9.63 partially specifies key formats, it does it in a less than ideally simple manner.  \
3664In the case of LibTomCrypt, it is meant \textbf{solely} for NIST and SECG $GF(p)$ curves.  The format of the keys is as follows:
3665
3666\index{ECC Key Format}
3667\begin{small}
3668\begin{verbatim}
3669ECCPublicKey ::= SEQUENCE {
3670    flags       BIT STRING(0), -- public/private flag (always zero),
3671    keySize     INTEGER,       -- Curve size (in bits) divided by eight
3672                               -- and rounded down, e.g. 521 => 65
3673    pubkey.x    INTEGER,       -- The X co-ordinate of the public key point
3674    pubkey.y    INTEGER,       -- The Y co-ordinate of the public key point
3675}
3676
3677ECCPrivateKey ::= SEQUENCE {
3678    flags       BIT STRING(1), -- public/private flag (always one),
3679    keySize     INTEGER,       -- Curve size (in bits) divided by eight
3680                               -- and rounded down, e.g. 521 => 65
3681    pubkey.x    INTEGER,       -- The X co-ordinate of the public key point
3682    pubkey.y    INTEGER,       -- The Y co-ordinate of the public key point
3683    secret.k    INTEGER,       -- The secret key scalar
3684}
3685\end{verbatim}
3686\end{small}
3687
3688The first flags bit denotes whether the key is public (zero) or private (one).
3689
3690\vfil
3691
3692\mysection{ECC Curve Parameters}
3693The library uses the following structure to describe an elliptic curve.  This is used internally, as well as by the new
3694extended ECC functions which allow the user to specify their own curves.
3695
3696\index{ltc\_ecc\_set\_type}
3697\begin{verbatim}
3698/** Structure defines a NIST GF(p) curve */
3699typedef struct {
3700   /** The size of the curve in octets */
3701   int size;
3702
3703   /** name of curve */
3704   char *name;
3705
3706   /** The prime that defines the field (encoded in hex) */
3707   char *prime;
3708
3709   /** The fields B param (hex) */
3710   char *B;
3711
3712   /** The order of the curve (hex) */
3713   char *order;
3714
3715   /** The x co-ordinate of the base point on the curve (hex) */
3716   char *Gx;
3717
3718   /** The y co-ordinate of the base point on the curve (hex) */
3719   char *Gy;
3720} ltc_ecc_set_type;
3721\end{verbatim}
3722
3723The curve must be of the form $y^2 = x^3 - 3x + b$, and all of the integer parameters are encoded in hexadecimal format.
3724
3725\mysection{Core Functions}
3726\subsection{ECC Key Generation}
3727There is a key structure called \textit{ecc\_key} used by the ECC functions.  There is a function to make a key:
3728\index{ecc\_make\_key()}
3729\begin{verbatim}
3730int ecc_make_key(prng_state *prng,
3731                        int  wprng,
3732                        int  keysize,
3733                    ecc_key *key);
3734\end{verbatim}
3735
3736The \textit{keysize} is the size of the modulus in bytes desired.  Currently directly supported values are 12, 16, 20, 24, 28, 32, 48, and 65 bytes which
3737correspond to key sizes of 112, 128, 160, 192, 224, 256, 384, and 521 bits respectively.  If you pass a key size that is between any key size it will round
3738the keysize up to the next available one.
3739
3740The function will free any internally allocated resources if there is an error.
3741
3742\subsection{Extended Key Generation}
3743As of v1.16, the library supports an extended key generation routine which allows the user to specify their own curve.  It is specified as follows:
3744
3745\index{ecc\_make\_key\_ex()}
3746\begin{verbatim}
3747int  ecc_make_key_ex(
3748                 prng_state *prng,
3749                        int  wprng,
3750                    ecc_key *key,
3751     const ltc_ecc_set_type *dp);
3752\end{verbatim}
3753
3754This function generates a random ECC key over the curve specified by the parameters by \textit{dp}.  The rest of the parameters are equivalent to
3755those from the original key generation function.
3756
3757\subsection{ECC Key Free}
3758To free the memory allocated by a ecc\_make\_key(), ecc\_make\_key\_ex(), ecc\_import(), or ecc\_import\_ex() call use the following function:
3759\index{ecc\_free()}
3760\begin{verbatim}
3761void ecc_free(ecc_key *key);
3762\end{verbatim}
3763
3764\subsection{ECC Key Export}
3765To export an ECC key using the LibTomCrypt format call the following function:
3766\index{ecc\_export()}
3767\begin{verbatim}
3768int ecc_export(unsigned char *out,
3769               unsigned long *outlen,
3770                         int  type,
3771                     ecc_key *key);
3772\end{verbatim}
3773This will export the key with the given \textit{type} (\textbf{PK\_PUBLIC} or \textbf{PK\_PRIVATE}), and store it to \textit{out}.
3774
3775\subsection{ECC Key Import}
3776The following function imports a LibTomCrypt format ECC key:
3777\index{ecc\_import()}
3778\begin{verbatim}
3779int ecc_import(const unsigned char *in,
3780                     unsigned long  inlen,
3781                           ecc_key *key);
3782\end{verbatim}
3783This will import the ECC key from \textit{in}, and store it in the ecc\_key structure pointed to by \textit{key}.  If the operation fails it will free
3784any allocated memory automatically.
3785
3786\subsection{Extended Key Import}
3787
3788The following function imports a LibTomCrypt format ECC key using a specified set of curve parameters:
3789\index{ecc\_import\_ex()}
3790\begin{verbatim}
3791int  ecc_import_ex(const unsigned char *in,
3792                         unsigned long  inlen,
3793                               ecc_key *key,
3794                const ltc_ecc_set_type *dp);
3795\end{verbatim}
3796This will import the key from the array pointed to by \textit{in} of length \textit{inlen} octets.  The key is stored in
3797the ECC structure pointed to by \textit{key}.  The curve is specified by the parameters pointed to by \textit{dp}.  The function will free
3798all internally allocated memory upon error.
3799
3800\subsection{ANSI X9.63 Export}
3801The following function exports an ECC public key in the ANSI X9.63 format:
3802
3803\index{ecc\_ansi\_x963\_export()}
3804\begin{verbatim}
3805int ecc_ansi_x963_export(      ecc_key *key,
3806                         unsigned char *out,
3807                         unsigned long *outlen);
3808\end{verbatim}
3809The ECC key pointed to by \textit{key} is exported in public fashion to the array pointed to by \textit{out}.  The ANSI X9.63 format used is from
3810section 4.3.6 of the standard.  It does not allow for the export of private keys.
3811
3812\subsection{ANSI X9.63 Import}
3813The following function imports an ANSI X9.63 section 4.3.6 format public ECC key:
3814
3815\index{ecc\_ansi\_x963\_import()}
3816\begin{verbatim}
3817int ecc_ansi_x963_import(const unsigned char *in,
3818                               unsigned long  inlen,
3819                                     ecc_key *key);
3820\end{verbatim}
3821This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets.  The imported key is stored in the ECC key pointed to by
3822\textit{key}.  The function will free any allocated memory upon error.
3823
3824\subsection{Extended ANSI X9.63 Import}
3825The following function allows the importing of an ANSI x9.63 section 4.3.6 format public ECC key using user specified domain parameters:
3826
3827\index{ecc\_ansi\_x963\_import\_ex()}
3828\begin{verbatim}
3829int ecc_ansi_x963_import_ex(const unsigned char *in,
3830                                  unsigned long  inlen,
3831                                        ecc_key *key,
3832                               ltc_ecc_set_type *dp);
3833\end{verbatim}
3834This will import the key stored in the array pointed to by \textit{in} of length \textit{inlen} octets using the domain parameters pointed to by \textit{dp}.
3835The imported key is stored in the ECC key pointed to by \textit{key}.  The function will free any allocated memory upon error.
3836
3837\subsection{ECC Shared Secret}
3838To construct a Diffie-Hellman shared secret with a private and public ECC key, use the following function:
3839\index{ecc\_shared\_secret()}
3840\begin{verbatim}
3841int ecc_shared_secret(      ecc_key *private_key,
3842                            ecc_key *public_key,
3843                      unsigned char *out,
3844                      unsigned long *outlen);
3845\end{verbatim}
3846The \textit{private\_key} is typically the local private key, and \textit{public\_key} is the key the remote party has shared.
3847Note: this function stores only the $x$ co-ordinate of the shared elliptic point as described in ANSI X9.63 ECC--DH.
3848
3849\mysection{ECC Diffie-Hellman Encryption}
3850ECC--DH Encryption is performed by producing a random key, hashing it, and XOR'ing the digest against the plaintext.  It is not strictly ANSI X9.63 compliant
3851but it is very similar.  It has been extended by using an ASN.1 sequence and hash object identifiers to allow portable usage.  The following function
3852encrypts a short string (no longer than the message digest) using this technique:
3853
3854\subsection{ECC-DH Encryption}
3855\index{ecc\_encrypt\_key()}
3856\begin{verbatim}
3857int ecc_encrypt_key(const unsigned char *in,
3858                          unsigned long  inlen,
3859                          unsigned char *out,
3860                          unsigned long *outlen,
3861                             prng_state *prng,
3862                                    int  wprng,
3863                                    int  hash,
3864                                ecc_key *key);
3865\end{verbatim}
3866
3867As the name implies this function encrypts a (symmetric) key, and is not intended for encrypting long messages directly.  It will encrypt the
3868plaintext in the array pointed to by \textit{in} of length \textit{inlen} octets.  It uses the public ECC key pointed to by \textit{key}, and
3869hash algorithm indexed by \textit{hash} to construct a shared secret which may be XOR'ed against the plaintext.  The ciphertext is stored in
3870the output buffer pointed to by \textit{out} of length \textit{outlen} octets.
3871
3872The data is encrypted to the public ECC \textit{key} such that only the holder of the private key can decrypt the payload.  To have multiple
3873recipients multiple call to this function for each public ECC key is required.
3874
3875\subsection{ECC-DH Decryption}
3876\index{ecc\_decrypt\_key()}
3877\begin{verbatim}
3878int ecc_decrypt_key(const unsigned char *in,
3879                          unsigned long  inlen,
3880                          unsigned char *out,
3881                          unsigned long *outlen,
3882                                ecc_key *key);
3883\end{verbatim}
3884
3885This function will decrypt an encrypted payload.  The \textit{key} provided must be the private key corresponding to the public key
3886used during encryption.  If the wrong key is provided the function will not specifically return an error code.  It is important
3887to use some form of challenge response in that case (e.g. compute a MAC of a known string).
3888
3889\subsection{ECC Encryption Format}
3890The packet format for the encrypted keys is the following ASN.1 SEQUENCE:
3891
3892\begin{verbatim}
3893ECCEncrypt ::= SEQUENCE {
3894   hashID        OBJECT IDENTIFIER, -- OID of hash used
3895   pubkey        OCTET STRING     , -- Encapsulated ECCPublicKey
3896   skey          OCTET STRING       -- xor of plaintext and
3897                                    --"hash of shared secret"
3898}
3899\end{verbatim}
3900
3901\mysection{EC DSA Signatures}
3902
3903There are also functions to sign and verify messages.  They use the ANSI X9.62 EC-DSA algorithm to generate and verify signatures in the
3904ANSI X9.62 format.
3905
3906\subsection{EC-DSA Signature Generation}
3907To sign a message digest (hash) use the following function:
3908
3909\index{ecc\_sign\_hash()}
3910\begin{verbatim}
3911int ecc_sign_hash(const unsigned char *in,
3912                        unsigned long  inlen,
3913                        unsigned char *out,
3914                        unsigned long *outlen,
3915                           prng_state *prng,
3916                                  int  wprng,
3917                              ecc_key *key);
3918\end{verbatim}
3919
3920This function will EC--DSA sign the message digest stored in the array pointed to by \textit{in} of length \textit{inlen} octets.  The signature
3921will be stored in the array pointed to by \textit{out} of length \textit{outlen} octets.  The function requires a properly seeded PRNG, and
3922the ECC \textit{key} provided must be a private key.
3923
3924\subsection{EC-DSA Signature Verification}
3925\index{ecc\_verify\_hash()}
3926\begin{verbatim}
3927int ecc_verify_hash(const unsigned char *sig,
3928                          unsigned long  siglen,
3929                    const unsigned char *hash,
3930                          unsigned long  hashlen,
3931                                    int *stat,
3932                                ecc_key *key);
3933\end{verbatim}
3934
3935This function will verify the EC-DSA signature in the array pointed to by \textit{sig} of length \textit{siglen} octets, against the message digest
3936pointed to by the array \textit{hash} of length \textit{hashlen}.  It will store a non--zero value in \textit{stat} if the signature is valid.  Note:
3937the function will not return an error if the signature is invalid.  It will return an error, if the actual signature payload is an invalid format.
3938The ECC \textit{key} must be the public (or private) ECC key corresponding to the key that performed the signature.
3939
3940\subsection{Signature Format}
3941The signature code is an implementation of X9.62 EC--DSA, and the output is compliant for GF(p) curves.
3942
3943\mysection{ECC Keysizes}
3944With ECC if you try to 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
3945work.  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
3946SHA256 and an ECC-192 key, you in effect have 96--bits of security.
3947
3948The library will not warn you if you make this mistake, so it is important to check yourself before using the signatures.
3949
3950\chapter{Digital Signature Algorithm}
3951\mysection{Introduction}
3952The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to
3953reduce the bandwidth of the signatures.  For example, to have \textit{80-bits of security} with ElGamal, you need a group with an order of at least 1024--bits.
3954With DSA, you need a group of order at least 160--bits.  By comparison, the ElGamal signature would require at least 256 bytes of storage, whereas the DSA signature
3955would require only at least 40 bytes.
3956
3957\mysection{Key Format}
3958Since no useful public standard for DSA key storage was presented to me during the course of this development I made my own ASN.1 SEQUENCE which I document
3959now so that others can interoperate with this library.
3960
3961\begin{verbatim}
3962DSAPublicKey ::= SEQUENCE {
3963    publicFlags    BIT STRING(0), -- must be 0
3964    g              INTEGER      , -- base generator
3965                                  -- check that g^q mod p == 1
3966                                  -- and that 1 < g < p - 1
3967    p              INTEGER      , -- prime modulus
3968    q              INTEGER      , -- order of sub-group
3969                                  -- (must be prime)
3970    y              INTEGER      , -- public key, specifically,
3971                                  -- g^x mod p,
3972                                  -- check that y^q mod p == 1
3973                                  -- and that 1 < y < p - 1
3974}
3975
3976DSAPrivateKey ::= SEQUENCE {
3977    publicFlags    BIT STRING(1), -- must be 1
3978    g              INTEGER      , -- base generator
3979                                  -- check that g^q mod p == 1
3980                                  -- and that 1 < g < p - 1
3981    p              INTEGER      , -- prime modulus
3982    q              INTEGER      , -- order of sub-group
3983                                  -- (must be prime)
3984    y              INTEGER      , -- public key, specifically,
3985                                  -- g^x mod p,
3986                                  -- check that y^q mod p == 1
3987                                  -- and that 1 < y < p - 1
3988    x              INTEGER        -- private key
3989}
3990\end{verbatim}
3991
3992The leading BIT STRING has a single bit in it which is zero for public keys and one for private keys.  This makes the structure uniquely decodable,
3993and easy to work with.
3994
3995\mysection{Key Generation}
3996To make a DSA key you must call the following function
3997\begin{verbatim}
3998int dsa_make_key(prng_state *prng,
3999                        int  wprng,
4000                        int  group_size,
4001                        int  modulus_size,
4002                    dsa_key *key);
4003\end{verbatim}
4004The variable \textit{prng} is an active PRNG state and \textit{wprng} the index to the descriptor.  \textit{group\_size} and
4005\textit{modulus\_size} control the difficulty of forging a signature.  Both parameters are in bytes.  The larger the
4006\textit{group\_size} the more difficult a forgery becomes upto a limit.  The value of $group\_size$ is limited by
4007$15 < group\_size < 1024$ and $modulus\_size - group\_size < 512$.  Suggested values for the pairs are as follows.
4008
4009\begin{figure}[here]
4010\begin{center}
4011\begin{tabular}{|c|c|c|}
4012\hline \textbf{Bits of Security} & \textbf{group\_size} & \textbf{modulus\_size} \\
4013\hline 80  & 20 & 128 \\
4014\hline 120 & 30 & 256 \\
4015\hline 140 & 35 & 384 \\
4016\hline 160 & 40 & 512 \\
4017\hline
4018\end{tabular}
4019\end{center}
4020\caption{DSA Key Sizes}
4021\end{figure}
4022
4023When you are finished with a DSA key you can call the following function to free the memory used.
4024\index{dsa\_free()}
4025\begin{verbatim}
4026void dsa_free(dsa_key *key);
4027\end{verbatim}
4028
4029\mysection{Key Verification}
4030Each DSA key is composed of the following variables.
4031
4032\begin{enumerate}
4033  \item $q$ a small prime of magnitude $256^{group\_size}$.
4034  \item $p = qr + 1$ a large prime of magnitude $256^{modulus\_size}$ where $r$ is a random even integer.
4035  \item $g = h^r \mbox{ (mod }p\mbox{)}$ a generator of order $q$ modulo $p$.  $h$ can be any non-trivial random
4036        value.  For this library they start at $h = 2$ and step until $g$ is not $1$.
4037  \item $x$ a random secret (the secret key) in the range $1 < x < q$
4038  \item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key.
4039\end{enumerate}
4040
4041A DSA key is considered valid if it passes all of the following tests.
4042
4043\begin{enumerate}
4044   \item $q$ must be prime.
4045   \item $p$ must be prime.
4046   \item $g$ cannot be one of $\lbrace -1, 0, 1 \rbrace$ (modulo $p$).
4047   \item $g$ must be less than $p$.
4048   \item $(p-1) \equiv 0 \mbox{ (mod }q\mbox{)}$.
4049   \item $g^q \equiv 1 \mbox{ (mod }p\mbox{)}$.
4050   \item $1 < y < p - 1$
4051   \item $y^q \equiv 1 \mbox{ (mod }p\mbox{)}$.
4052\end{enumerate}
4053
4054Tests one and two ensure that the values will at least form a field which is required for the signatures to
4055function.  Tests three and four ensure that the generator $g$ is not set to a trivial value which would make signature
4056forgery easier.  Test five ensures that $q$ divides the order of multiplicative sub-group of $\Z/p\Z$. Test six
4057ensures that the generator actually generates a prime order group.  Tests seven and eight ensure that the public key
4058is within range and belongs to a group of prime order.  Note that test eight does not prove that $g$ generated $y$ only
4059that $y$ belongs to a multiplicative sub-group of order $q$.
4060
4061The following function will perform these tests.
4062
4063\index{dsa\_verify\_key()}
4064\begin{verbatim}
4065int dsa_verify_key(dsa_key *key, int *stat);
4066\end{verbatim}
4067
4068This will test \textit{key} and store the result in \textit{stat}.  If the result is $stat = 0$ the DSA key failed one of the tests
4069and should not be used at all.  If the result is $stat = 1$ the DSA key is valid (as far as valid mathematics are concerned).
4070
4071\mysection{Signatures}
4072\subsection{Signature Generation}
4073To generate a DSA signature call the following function:
4074
4075\index{dsa\_sign\_hash()}
4076\begin{verbatim}
4077int dsa_sign_hash(const unsigned char *in,
4078                        unsigned long  inlen,
4079                        unsigned char *out,
4080                        unsigned long *outlen,
4081                           prng_state *prng,
4082                                  int  wprng,
4083                              dsa_key *key);
4084\end{verbatim}
4085
4086Which will sign the data in \textit{in} of length \textit{inlen} bytes.  The signature is stored in \textit{out} and the size
4087of the signature in \textit{outlen}.  If the signature is longer than the size you initially specify in \textit{outlen} nothing
4088is stored and the function returns an error code.  The DSA \textit{key} must be of the \textbf{PK\_PRIVATE} persuasion.
4089
4090\subsection{Signature Verification}
4091To verify a hash created with that function use the following function:
4092
4093\index{dsa\_verify\_hash()}
4094\begin{verbatim}
4095int dsa_verify_hash(const unsigned char *sig,
4096                          unsigned long  siglen,
4097                    const unsigned char *hash,
4098                          unsigned long  inlen,
4099                                    int *stat,
4100                                dsa_key *key);
4101\end{verbatim}
4102Which will verify the data in \textit{hash} of length \textit{inlen} against the signature stored in \textit{sig} of length \textit{siglen}.
4103It will set \textit{stat} to $1$ if the signature is valid, otherwise it sets \textit{stat} to $0$.
4104
4105\mysection{DSA Encrypt and Decrypt}
4106As of version 1.07, the DSA keys can be used to encrypt and decrypt small payloads.  It works similar to the ECC encryption where
4107a shared key is computed, and the hash of the shared key XOR'ed against the plaintext forms the ciphertext.  The format used is functional port of
4108the ECC encryption format to the DSA algorithm.
4109
4110\subsection{DSA Encryption}
4111This function will encrypt a small payload with a recipients public DSA key.
4112
4113\index{dsa\_encrypt\_key()}
4114\begin{verbatim}
4115int dsa_encrypt_key(const unsigned char *in,
4116                          unsigned long  inlen,
4117                          unsigned char *out,
4118                          unsigned long *outlen,
4119                             prng_state *prng,
4120                                    int  wprng,
4121                                    int  hash,
4122                                dsa_key *key);
4123\end{verbatim}
4124
4125This will encrypt the payload in \textit{in} of length \textit{inlen} and store the ciphertext in the output buffer \textit{out}.  The
4126length of the ciphertext \textit{outlen} must be originally set to the length of the output buffer.  The DSA \textit{key} can be
4127a public key.
4128
4129\subsection{DSA Decryption}
4130
4131\index{dsa\_decrypt\_key()}
4132\begin{verbatim}
4133int dsa_decrypt_key(const unsigned char *in,
4134                          unsigned long  inlen,
4135                          unsigned char *out,
4136                          unsigned long *outlen,
4137                                dsa_key *key);
4138\end{verbatim}
4139This will decrypt the ciphertext \textit{in} of length \textit{inlen}, and store the original payload in \textit{out} of length \textit{outlen}.
4140The DSA \textit{key} must be a private key.
4141
4142\mysection{DSA Key Import and Export}
4143
4144\subsection{DSA Key Export}
4145To export a DSA key so that it can be transported use the following function:
4146\index{dsa\_export()}
4147\begin{verbatim}
4148int dsa_export(unsigned char *out,
4149               unsigned long *outlen,
4150                         int  type,
4151                     dsa_key *key);
4152\end{verbatim}
4153This will export the DSA \textit{key} to the buffer \textit{out} and set the length in \textit{outlen} (which must have been previously
4154initialized to the maximum buffer size).  The \textit{type} variable may be either \textbf{PK\_PRIVATE} or \textbf{PK\_PUBLIC}
4155depending on whether you want to export a private or public copy of the DSA key.
4156
4157\subsection{DSA Key Import}
4158To import an exported DSA key use the following function
4159:
4160\index{dsa\_import()}
4161\begin{verbatim}
4162int dsa_import(const unsigned char *in,
4163                     unsigned long  inlen,
4164                           dsa_key *key);
4165\end{verbatim}
4166
4167This will import the DSA key from the buffer \textit{in} of length \textit{inlen} to the \textit{key}.  If the process fails the function
4168will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()).
4169
4170\chapter{Standards Support}
4171\mysection{ASN.1 Formats}
4172LibTomCrypt supports a variety of ASN.1 data types encoded with the Distinguished Encoding Rules (DER) suitable for various cryptographic protocols.  The data types
4173are all provided with three basic functions with \textit{similar} prototypes.  One function has been dedicated to calculate the length in octets of a given
4174format, and two functions have been dedicated to encoding and decoding the format.
4175
4176On top of the basic data types are the SEQUENCE and SET data types which are collections of other ASN.1 types.  They are provided
4177in the same manner as the other data types except they use list of objects known as the \textbf{ltc\_asn1\_list} structure.  It is defined as the following:
4178
4179\index{ltc\_asn1\_list structure}
4180\begin{verbatim}
4181typedef struct {
4182   int                    type;
4183   void                  *data;
4184   unsigned long          size;
4185   int                    used;
4186   struct ltc_asn1_list_ *prev,  *next,
4187                         *child, *parent;
4188} ltc_asn1_list;
4189\end{verbatim}
4190
4191\index{LTC\_SET\_ASN1 macro}
4192The \textit{type} field is one of the following ASN.1 field definitions.  The \textit{data} pointer is a void pointer to the data to be encoded (or the destination) and the
4193\textit{size} field is specific to what you are encoding (e.g. number of bits in the BIT STRING data type).  The \textit{used} field is primarily for the CHOICE decoder
4194and reflects if the particular member of a list was the decoded data type.  To help build the lists in an orderly fashion the macro
4195\textit{LTC\_SET\_ASN1(list, index, Type, Data, Size)} has been provided.
4196
4197It will assign to the \textit{index}th position in the \textit{list} the triplet (Type, Data, Size).  An example usage would be:
4198
4199\begin{small}
4200\begin{verbatim}
4201...
4202ltc_asn1_list   sequence[3];
4203unsigned long   three=3;
4204
4205LTC_SET_ASN1(sequence, 0, LTC_ASN1_IA5_STRING,    "hello", 5);
4206LTC_SET_ASN1(sequence, 1, LTC_ASN1_SHORT_INTEGER, &three,  1);
4207LTC_SET_ASN1(sequence, 2, LTC_ASN1_NULL,           NULL,   0);
4208\end{verbatim}
4209\end{small}
4210
4211The macro is relatively safe with respect to modifying variables, for instance the following code is equivalent.
4212
4213\begin{small}
4214\begin{verbatim}
4215...
4216ltc_asn1_list   sequence[3];
4217unsigned long   three=3;
4218int             x=0;
4219LTC_SET_ASN1(sequence, x++, LTC_ASN1_IA5_STRING,    "hello", 5);
4220LTC_SET_ASN1(sequence, x++, LTC_ASN1_SHORT_INTEGER, &three,  1);
4221LTC_SET_ASN1(sequence, x++, LTC_ASN1_NULL,           NULL,   0);
4222\end{verbatim}
4223\end{small}
4224
4225\begin{figure}[here]
4226\begin{center}
4227\begin{small}
4228\begin{tabular}{|l|l|}
4229\hline \textbf{Definition}           & \textbf{ASN.1 Type} \\
4230\hline LTC\_ASN1\_EOL                & End of a ASN.1 list structure. \\
4231\hline LTC\_ASN1\_BOOLEAN            & BOOLEAN type \\
4232\hline LTC\_ASN1\_INTEGER            & INTEGER (uses mp\_int) \\
4233\hline LTC\_ASN1\_SHORT\_INTEGER     & INTEGER (32--bit using unsigned long) \\
4234\hline LTC\_ASN1\_BIT\_STRING        & BIT STRING (one bit per char) \\
4235\hline LTC\_ASN1\_OCTET\_STRING      & OCTET STRING (one octet per char) \\
4236\hline LTC\_ASN1\_NULL               & NULL \\
4237\hline LTC\_ASN1\_OBJECT\_IDENTIFIER & OBJECT IDENTIFIER  \\
4238\hline LTC\_ASN1\_IA5\_STRING        & IA5 STRING (one octet per char) \\
4239\hline LTC\_ASN1\_UTF8\_STRING       & UTF8 STRING (one wchar\_t per char) \\
4240\hline LTC\_ASN1\_PRINTABLE\_STRING  & PRINTABLE STRING (one octet per char) \\
4241\hline LTC\_ASN1\_UTCTIME            & UTCTIME (see ltc\_utctime structure) \\
4242\hline LTC\_ASN1\_SEQUENCE           & SEQUENCE (and SEQUENCE OF) \\
4243\hline LTC\_ASN1\_SET                & SET \\
4244\hline LTC\_ASN1\_SETOF              & SET OF \\
4245\hline LTC\_ASN1\_CHOICE             & CHOICE \\
4246\hline
4247\end{tabular}
4248\caption{List of ASN.1 Supported Types}
4249\end{small}
4250\end{center}
4251\end{figure}
4252
4253\subsection{SEQUENCE Type}
4254The SEQUENCE data type is a collection of other ASN.1 data types encapsulated with a small header which is a useful way of sending multiple data types in one packet.
4255
4256\subsubsection{SEQUENCE Encoding}
4257To encode a sequence a \textbf{ltc\_asn1\_list} array must be initialized with the members of the sequence and their respective pointers.  The encoding is performed
4258with the following function.
4259
4260\index{der\_encode\_sequence()}
4261\begin{verbatim}
4262int der_encode_sequence(ltc_asn1_list *list,
4263                        unsigned long  inlen,
4264                        unsigned char *out,
4265                        unsigned long *outlen);
4266\end{verbatim}
4267This encodes a sequence of items pointed to by \textit{list} where the list has \textit{inlen} items in it.  The SEQUENCE will be encoded to \textit{out} and of length \textit{outlen}.  The
4268function will terminate when it reads all the items out of the list (upto \textit{inlen}) or it encounters an item in the list with a type of \textbf{LTC\_ASN1\_EOL}.
4269
4270The \textit{data} pointer in the list would be the same pointer you would pass to the respective ASN.1 encoder (e.g. der\_encode\_bit\_string()) and it is simply passed on
4271verbatim to the dependent encoder.  The list can contain other SEQUENCE or SET types which enables you to have nested SEQUENCE and SET definitions.  In these cases
4272the \textit{data} pointer is simply a pointer to another \textbf{ltc\_asn1\_list}.
4273
4274\subsubsection{SEQUENCE Decoding}
4275
4276\index{der\_decode\_sequence()}
4277
4278Decoding a SEQUENCE is similar to encoding.  You set up an array of \textbf{ltc\_asn1\_list} where in this case the \textit{size} member is the maximum size
4279(in certain cases).  For types such as IA5 STRING, BIT STRING, OCTET STRING (etc) the \textit{size} field is updated after successful decoding to reflect how many
4280units of the respective type has been loaded.
4281
4282\begin{verbatim}
4283int der_decode_sequence(const unsigned char *in,
4284                              unsigned long  inlen,
4285                              ltc_asn1_list *list,
4286                              unsigned long  outlen);
4287\end{verbatim}
4288
4289This will decode upto \textit{outlen} items from the input buffer \textit{in} of length \textit{inlen} octets.  The function will stop (gracefully) when it runs out of items to decode.
4290It will fail (for among other reasons) when it runs out of input bytes to read, a data type is invalid or a heap failure occurred.
4291
4292For the following types the \textit{size} field will be updated to reflect the number of units read of the given type.
4293\begin{enumerate}
4294   \item BIT STRING
4295   \item OCTET STRING
4296   \item OBJECT IDENTIFIER
4297   \item IA5 STRING
4298   \item PRINTABLE STRING
4299\end{enumerate}
4300
4301\subsubsection{SEQUENCE Length}
4302
4303The length of a SEQUENCE can be determined with the following function.
4304
4305\index{der\_length\_sequence()}
4306\begin{verbatim}
4307int der_length_sequence(ltc_asn1_list *list,
4308                        unsigned long  inlen,
4309                        unsigned long *outlen);
4310\end{verbatim}
4311
4312This will get the encoding size for the given \textit{list} of length \textit{inlen} and store it in \textit{outlen}.
4313
4314\subsubsection{SEQUENCE Multiple Argument Lists}
4315
4316For small or simple sequences an encoding or decoding can be performed with one of the following two functions.
4317
4318\index{der\_encode\_sequence\_multi()}
4319\index{der\_decode\_sequence\_multi()}
4320
4321\begin{verbatim}
4322int der_encode_sequence_multi(unsigned char *out,
4323                              unsigned long *outlen, ...);
4324
4325int der_decode_sequence_multi(const unsigned char *in,
4326                                    unsigned long  inlen, ...);
4327\end{verbatim}
4328
4329These either encode or decode (respectively) a SEQUENCE data type where the items in the sequence are specified after the length parameter.
4330
4331The list of items are specified as a triple of the form \textit{(type, size, data)}  where \textit{type} is an \textbf{int}, \textit{size} is a \textbf{unsigned long}
4332and \textit{data} is \textbf{void} pointer.  The list of items must be terminated with an item with the type \textbf{LTC\_ASN1\_EOL}.
4333
4334It is ideal that you cast the \textit{size} values to unsigned long to ensure that the proper data type is passed to the function.  Constants such as \textit{1} without
4335a cast or prototype are of type \textbf{int} by default.  Appending \textit{UL} or pre-pending \textit{(unsigned long)} is enough to cast it to the correct type.
4336
4337\begin{small}
4338\begin{verbatim}
4339unsigned char buf[MAXBUFSIZE];
4340unsigned long buflen;
4341int           err;
4342
4343   buflen = sizeof(buf);
4344   if ((err =
4345        der_encode_sequence_multi(buf, &buflen,
4346        LTC_ASN1_IA5_STRING, 5UL, "Hello",
4347        LTC_ASN1_IA5_STRING, 7UL, " World!",
4348        LTC_ASN1_EOL,        0UL, NULL)) != CRYPT_OK) {
4349      // error handling
4350   }
4351\end{verbatim}
4352\end{small}
4353
4354This example encodes a SEQUENCE with two IA5 STRING types containing ``Hello'' and `` World!'' respectively.  Note the usage of the \textbf{UL} modifier
4355on the size parameters.  This forces the compiler to pass the numbers as the required \textbf{unsigned long} type that the function expects.
4356
4357\subsection{SET and SET OF}
4358
4359\index{SET} \index{SET OF}
4360SET and SET OF are related to the SEQUENCE type in that they can be pretty much be decoded with the same code.  However, they are different, and they should
4361be carefully noted.  The SET type is an unordered array of ASN.1 types sorted by the TAG (type identifier), whereas the SET OF type is an ordered array of
4362a \textbf{single} ASN.1 object sorted in ascending order by the DER their respective encodings.
4363
4364\subsubsection{SET Encoding}
4365
4366SETs use the same array structure of ltc\_asn1\_list that the SEQUENCE functions use.  They are encoded with the following function:
4367
4368\index{der\_encode\_set()}
4369\begin{verbatim}
4370int der_encode_set(ltc_asn1_list *list,
4371                   unsigned long  inlen,
4372                   unsigned char *out,
4373                   unsigned long *outlen);
4374\end{verbatim}
4375
4376This will encode the list of ASN.1 objects in \textit{list} of length \textit{inlen} objects, and store the output in \textit{out} of length \textit{outlen} bytes.
4377The function will make a copy of the list provided, and sort it by the TAG.  Objects with identical TAGs are additionally sorted on their original placement in the
4378array (to make the process deterministic).
4379
4380This function will \textbf{NOT} recognize \textit{DEFAULT} objects, and it is the responsibility of the caller to remove them as required.
4381
4382\subsubsection{SET Decoding}
4383
4384The SET type can be decoded with the following function.
4385
4386\index{der\_decode\_set()}
4387\begin{verbatim}
4388int der_decode_set(const unsigned char *in,
4389                         unsigned long  inlen,
4390                         ltc_asn1_list *list,
4391                         unsigned long  outlen);
4392\end{verbatim}
4393
4394This will decode the SET specified by \textit{list} of length \textit{outlen} objects from the input buffer \textit{in} of length \textit{inlen} octets.
4395
4396It handles the fact that SETs are not strictly ordered and will make multiple passes (as required) through the list to decode all the objects.
4397
4398\subsubsection{SET Length}
4399The length of a SET can be determined by calling der\_length\_sequence() since they have the same encoding length.
4400
4401\subsubsection{SET OF Encoding}
4402A \textit{SET OF} object is an array of identical objects (e.g. OCTET STRING) sorted in ascending order by the DER encoding of the object.  They are
4403used to store objects deterministically based solely on their encoding.  It uses the same array structure of ltc\_asn1\_list that the SEQUENCE functions
4404use.  They are encoded with the following function.
4405
4406\index{der\_encode\_setof()}
4407\begin{verbatim}
4408int der_encode_setof(ltc_asn1_list *list,
4409                     unsigned long  inlen,
4410                     unsigned char *out,
4411                     unsigned long *outlen);
4412\end{verbatim}
4413
4414This will encode a \textit{SET OF} containing the \textit{list} of \textit{inlen} ASN.1 objects and store the encoding in the output buffer \textit{out} of length \textit{outlen}.
4415
4416The routine will first encode the SET OF in an unordered fashion (in a temporary buffer) then sort using the XQSORT macro and copy back to the output buffer.  This
4417means you need at least enough memory to keep an additional copy of the output on the heap.
4418
4419\subsubsection{SET OF Decoding}
4420Since the decoding of a \textit{SET OF} object is unambiguous it can be decoded with der\_decode\_sequence().
4421
4422\subsubsection{SET OF Length}
4423Like the SET type the der\_length\_sequence() function can be used to determine the length of a \textit{SET OF} object.
4424
4425\subsection{ASN.1 INTEGER}
4426
4427To encode or decode INTEGER data types use the following functions.
4428
4429\index{der\_encode\_integer()}\index{der\_decode\_integer()}\index{der\_length\_integer()}
4430\begin{verbatim}
4431int der_encode_integer(         void *num,
4432                       unsigned char *out,
4433                       unsigned long *outlen);
4434
4435int der_decode_integer(const unsigned char *in,
4436                             unsigned long  inlen,
4437                                      void *num);
4438
4439int der_length_integer(         void *num,
4440                       unsigned long *len);
4441\end{verbatim}
4442
4443These will encode or decode a signed INTEGER data type using the bignum data type to store the large INTEGER.  To encode smaller values without allocating
4444a bignum to store the value, the \textit{short} INTEGER functions were made available.
4445
4446\index{der\_encode\_short\_integer()}\index{der\_decode\_short\_integer()}\index{der\_length\_short\_integer()}
4447\begin{verbatim}
4448int der_encode_short_integer(unsigned long  num,
4449                             unsigned char *out,
4450                             unsigned long *outlen);
4451
4452int der_decode_short_integer(const unsigned char *in,
4453                                   unsigned long  inlen,
4454                                   unsigned long *num);
4455
4456int der_length_short_integer(unsigned long  num,
4457                             unsigned long *outlen);
4458\end{verbatim}
4459
4460These will encode or decode an unsigned \textbf{unsigned long} type (only reads upto 32--bits).  For values in the range $0 \dots 2^{32} - 1$ the integer
4461and short integer functions can encode and decode each others outputs.
4462
4463\subsection{ASN.1 BIT STRING}
4464
4465\index{der\_encode\_bit\_string()}\index{der\_decode\_bit\_string()}\index{der\_length\_bit\_string()}
4466\begin{verbatim}
4467int der_encode_bit_string(const unsigned char *in,
4468                                unsigned long  inlen,
4469                                unsigned char *out,
4470                                unsigned long *outlen);
4471
4472int der_decode_bit_string(const unsigned char *in,
4473                                unsigned long  inlen,
4474                                unsigned char *out,
4475                                unsigned long *outlen);
4476
4477int der_length_bit_string(unsigned long  nbits,
4478                          unsigned long *outlen);
4479\end{verbatim}
4480
4481These will encode or decode a BIT STRING data type.  The bits are passed in (or read out) using one \textbf{char} per bit.  A non--zero value will be interpreted
4482as a one bit, and a zero value a zero bit.
4483
4484\subsection{ASN.1 OCTET STRING}
4485
4486\index{der\_encode\_octet\_string()}\index{der\_decode\_octet\_string()}\index{der\_length\_octet\_string()}
4487\begin{verbatim}
4488int der_encode_octet_string(const unsigned char *in,
4489                                  unsigned long  inlen,
4490                                  unsigned char *out,
4491                                  unsigned long *outlen);
4492
4493int der_decode_octet_string(const unsigned char *in,
4494                                  unsigned long  inlen,
4495                                  unsigned char *out,
4496                                  unsigned long *outlen);
4497
4498int der_length_octet_string(unsigned long  noctets,
4499                            unsigned long *outlen);
4500\end{verbatim}
4501
4502These will encode or decode an OCTET STRING data type.  The octets are stored using one \textbf{unsigned char} each.
4503
4504\subsection{ASN.1 OBJECT IDENTIFIER}
4505
4506\index{der\_encode\_object\_identifier()}\index{der\_decode\_object\_identifier()}\index{der\_length\_object\_identifier()}
4507\begin{verbatim}
4508int der_encode_object_identifier(unsigned long *words,
4509                                 unsigned long  nwords,
4510                                 unsigned char *out,
4511                                 unsigned long *outlen);
4512
4513int der_decode_object_identifier(const unsigned char *in,
4514                                       unsigned long  inlen,
4515                                       unsigned long *words,
4516                                       unsigned long *outlen);
4517
4518int der_length_object_identifier(unsigned long *words,
4519                                 unsigned long  nwords,
4520                                 unsigned long *outlen);
4521\end{verbatim}
4522
4523These will encode or decode an OBJECT IDENTIFIER object.  The words of the OID are stored in individual \textbf{unsigned long} elements, and must be in the range
4524$0 \ldots 2^{32} - 1$.
4525
4526\subsection{ASN.1 IA5 STRING}
4527
4528\index{der\_encode\_ia5\_string()}\index{der\_decode\_ia5\_string()}\index{der\_length\_ia5\_string()}
4529\begin{verbatim}
4530int der_encode_ia5_string(const unsigned char *in,
4531                                unsigned long  inlen,
4532                                unsigned char *out,
4533                                unsigned long *outlen);
4534
4535int der_decode_ia5_string(const unsigned char *in,
4536                                unsigned long  inlen,
4537                                unsigned char *out,
4538                                unsigned long *outlen);
4539
4540int der_length_ia5_string(const unsigned char *octets,
4541                                unsigned long  noctets,
4542                                unsigned long *outlen);
4543\end{verbatim}
4544
4545These will encode or decode an IA5 STRING.  The characters are read or stored in individual \textbf{char} elements.  These functions performs internal character
4546to numerical conversions based on the conventions of the compiler being used.  For instance, on an x86\_32 machine 'A' == 65 but the same may not be true on
4547say a SPARC machine.  Internally, these functions have a table of literal characters and their numerical ASCII values.  This provides a stable conversion provided
4548that the build platform honours the run--time platforms character conventions.
4549
4550\subsection{ASN.1 PRINTABLE STRING}
4551
4552\index{der\_encode\_printable\_string()}\index{der\_decode\_printable\_string()}\index{der\_length\_printable\_string()}
4553\begin{verbatim}
4554int der_encode_printable_string(const unsigned char *in,
4555                                      unsigned long  inlen,
4556                                      unsigned char *out,
4557                                      unsigned long *outlen);
4558
4559int der_decode_printable_string(const unsigned char *in,
4560                                      unsigned long  inlen,
4561                                      unsigned char *out,
4562                                      unsigned long *outlen);
4563
4564int der_length_printable_string(const unsigned char *octets,
4565                                      unsigned long  noctets,
4566                                      unsigned long *outlen);
4567\end{verbatim}
4568
4569These will encode or decode an PRINTABLE STRING.  The characters are read or stored in individual \textbf{char} elements.  These functions performs internal character
4570to numerical conversions based on the conventions of the compiler being used.  For instance, on an x86\_32 machine 'A' == 65 but the same may not be true on
4571say a SPARC machine.  Internally, these functions have a table of literal characters and their numerical ASCII values.  This provides a stable conversion provided
4572that the build platform honours the run-time platforms character conventions.
4573
4574\subsection{ASN.1 UTF8 STRING}
4575
4576\index{der\_encode\_utf8\_string()}\index{der\_decode\_utf8\_string()}\index{der\_length\_utf8\_string()}
4577\begin{verbatim}
4578int der_encode_utf8_string(const wchar_t *in,
4579                           unsigned long  inlen,
4580                           unsigned char *out,
4581                           unsigned long *outlen);
4582
4583int der_decode_utf8_string(const unsigned char *in,
4584                                 unsigned long  inlen,
4585                                       wchar_t *out,
4586                                 unsigned long *outlen);
4587
4588int der_length_utf8_string(const wchar_t *octets,
4589                           unsigned long  noctets,
4590                           unsigned long *outlen);
4591\end{verbatim}
4592
4593These will encode or decode an UTF8 STRING.  The characters are read or stored in individual \textbf{wchar\_t} elements.  These function performs no internal
4594mapping and treat the characters as literals.
4595
4596These functions use the \textbf{wchar\_t} type which is not universally available.  In those cases, the library will typedef it to \textbf{unsigned long}.  If you
4597intend to use the ISO C functions for working with wide--char arrays, you should make sure that wchar\_t has been defined previously.
4598
4599\subsection{ASN.1 UTCTIME}
4600
4601The UTCTIME type is to store a date and time in ASN.1 format.  It uses the following structure to organize the time.
4602
4603\index{ltc\_utctime structure}
4604\begin{verbatim}
4605typedef struct {
4606   unsigned YY, /* year    00--99 */
4607            MM, /* month   01--12 */
4608            DD, /* day     01--31 */
4609            hh, /* hour    00--23 */
4610            mm, /* minute  00--59 */
4611            ss, /* second  00--59 */
4612            off_dir, /* timezone offset direction 0 == +, 1 == - */
4613            off_hh, /* timezone offset hours */
4614            off_mm; /* timezone offset minutes */
4615} ltc_utctime;
4616\end{verbatim}
4617
4618The time can be offset plus or minus a set amount of hours (off\_hh) and minutes (off\_mm).  When \textit{off\_dir} is zero, the time will be added otherwise it
4619will be subtracted.  For instance, the array $\lbrace 5, 6, 20, 22, 4, 00, 0, 5, 0 \rbrace$ represents the current time of
4620\textit{2005, June 20th, 22:04:00} with a time offset of +05h00.
4621
4622\index{der\_encode\_utctime()}\index{der\_decode\_utctime()}\index{der\_length\_utctime()}
4623\begin{verbatim}
4624int der_encode_utctime(  ltc_utctime *utctime,
4625                       unsigned char *out,
4626                       unsigned long *outlen);
4627
4628int der_decode_utctime(const unsigned char *in,
4629                             unsigned long *inlen,
4630                               ltc_utctime *out);
4631
4632int der_length_utctime(  ltc_utctime *utctime,
4633                       unsigned long *outlen);
4634\end{verbatim}
4635
4636The encoder will store time in one of the two ASN.1 formats, either \textit{YYMMDDhhmmssZ} or \textit{YYMMDDhhmmss$\pm$hhmm}, and perform minimal error checking on the
4637input.  The decoder will read all valid ASN.1 formats and perform range checking on the values (not complete but rational) useful for catching packet errors.
4638
4639It is suggested that decoded data be further scrutinized (e.g. days of month in particular).
4640
4641\subsection{ASN.1 CHOICE}
4642
4643The CHOICE ASN.1 type represents a union of ASN.1 types all of which are stored in a \textit{ltc\_asn1\_list}.  There is no encoder for the CHOICE type, only a
4644decoder.  The decoder will scan through the provided list attempting to use the appropriate decoder on the input packet.  The list can contain any ASN.1 data
4645type\footnote{Except it cannot have LTC\_ASN1\_INTEGER and LTC\_ASN1\_SHORT\_INTEGER simultaneously.} except for other CHOICE types.
4646
4647There is no encoder for the CHOICE type as the actual DER encoding is the encoding of the chosen type.
4648
4649\index{der\_decode\_choice()}
4650\begin{verbatim}
4651int der_decode_choice(const unsigned char *in,
4652                            unsigned long *inlen,
4653                            ltc_asn1_list *list,
4654                            unsigned long  outlen);
4655\end{verbatim}
4656
4657This will decode the input in the \textit{in} field of length \textit{inlen}.  It uses the provided ASN.1 list specified in the \textit{list} field which has
4658\textit{outlen} elements.  The \textit{inlen} field will be updated with the length of the decoded data type, as well as the respective entry in the \textit{list} field
4659will have the \textit{used} flag set to non--zero to reflect it was the data type decoded.
4660
4661\subsection{ASN.1 Flexi Decoder}
4662The ASN.1 \textit{flexi} decoder allows the developer to decode arbitrary ASN.1 DER packets (provided they use data types LibTomCrypt supports) without first knowing
4663the structure of the data.  Where der\_decode \_sequence() requires the developer to specify the data types to decode in advance the flexi decoder is entirely
4664free form.
4665
4666The flexi decoder uses the same \textit{ltc\_asn1\_list} but instead of being stored in an array it uses the linked list pointers \textit{prev}, \textit{next}, \textit{parent}
4667and \textit{child}.  The list works as a \textit{doubly-linked list} structure where decoded items at the same level are siblings (using next and prev) and items
4668encoded in a SEQUENCE are stored as a child element.
4669
4670When a SEQUENCE or SET has been encountered a SEQUENCE (or SET resp.) item will be added as a sibling (e.g. list.type == LTC\_ASN1\_SEQUENCE) and the child
4671pointer points to a new list of items contained within the object.
4672
4673\index{der\_decode\_sequence\_flexi()}
4674\begin{verbatim}
4675int  der_decode_sequence_flexi(const unsigned char *in,
4676                                     unsigned long *inlen,
4677                                    ltc_asn1_list **out);
4678\end{verbatim}
4679
4680This will decode items in the \textit{in} buffer of max input length \textit{inlen} and store the newly created pointer to the list in \textit{out}.  This function allocates
4681all required memory for the decoding.  It stores the number of octets read back into \textit{inlen}.
4682
4683The function will terminate when either it hits an invalid ASN.1 tag, or it reads \textit{inlen} octets.  An early termination is a soft error, and returns
4684normally.  The decoded list \textit{out} will point to the very first element of the list (e.g. both parent and prev pointers will be \textbf{NULL}).
4685
4686An invalid decoding will terminate the process, and free the allocated memory automatically.
4687
4688\textbf{Note:} the list decoded by this function is \textbf{NOT} in the correct form for der\_encode\_sequence() to use directly.  You will have to first
4689have to convert the list by first storing all of the siblings in an array then storing all the children as sub-lists of a sequence using the \textit{.data}
4690pointer.  Currently no function in LibTomCrypt provides this ability.
4691
4692\subsubsection{Sample Decoding}
4693Suppose we decode the following structure:
4694\begin{small}
4695\begin{verbatim}
4696User ::= SEQUENCE {
4697   Name        IA5 STRING
4698   LoginToken  SEQUENCE {
4699      passwdHash   OCTET STRING
4700      pubkey       ECCPublicKey
4701   }
4702   LastOn      UTCTIME
4703}
4704\end{verbatim}
4705\end{small}
4706\begin{flushleft}and we decoded it with the following code:\end{flushleft}
4707
4708\begin{small}
4709\begin{verbatim}
4710unsigned char inbuf[MAXSIZE];
4711unsigned long inbuflen;
4712ltc_asn1_list *list;
4713int           err;
4714
4715/* somehow fill inbuf/inbuflen */
4716if ((err = der_decode_sequence_flexi(inbuf, inbuflen, &list)) != CRYPT_OK) {
4717   printf("Error decoding: %s\n", error_to_string(err));
4718   exit(EXIT_FAILURE);
4719}
4720\end{verbatim}
4721\end{small}
4722
4723At this point \textit{list} would point to the SEQUENCE identified by \textit{User}.  It would have no sibblings (prev or next), and only a child node.  Walking to the child
4724node with the following code will bring us to the \textit{Name} portion of the SEQUENCE:
4725\begin{small}
4726\begin{verbatim}
4727list = list->child;
4728\end{verbatim}
4729\end{small}
4730Now \textit{list} points to the \textit{Name} member (with the tag IA5 STRING).  The \textit{data}, \textit{size}, and \textit{type} members of \textit{list} should reflect
4731that of an IA5 STRING.  The sibbling will now be the \textit{LoginToken} SEQUENCE.  The sibbling has a child node which points to the \textit{passwdHash} OCTET STRING.
4732We can walk to this node with the following code:
4733\begin{small}
4734\begin{verbatim}
4735/* list already pointing to 'Name' */
4736list = list->next->child;
4737\end{verbatim}
4738\end{small}
4739At this point, \textit{list} will point to the \textit{passwdHash} member of the innermost SEQUENCE.  This node has a sibbling, the \textit{pubkey} member of the SEQUENCE.
4740The \textit{LastOn} member of the SEQUENCE is a sibbling of the LoginToken node, if we wanted to walk there we would have to go up and over via:
4741\begin{small}
4742\begin{verbatim}
4743list = list->parent->next;
4744\end{verbatim}
4745\end{small}
4746At this point, we are pointing to the last node of the list.  Lists are terminated in all directions by a \textbf{NULL} pointer.  All nodes are doubly linked so that you
4747can walk up and down the nodes without keeping pointers lying around.
4748
4749
4750
4751
4752
4753\subsubsection{Free'ing a Flexi List}
4754To free the list use the following function.
4755
4756\index{der\_sequence\_free()}
4757\begin{verbatim}
4758void der_sequence_free(ltc_asn1_list *in);
4759\end{verbatim}
4760
4761This will free all of the memory allocated by der\_decode\_sequence\_flexi().
4762
4763\mysection{Password Based Cryptography}
4764\subsection{PKCS \#5}
4765\index{PKCS \#5}
4766In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted.   PKCS \#5
4767is made up of two algorithms, Algorithm One and Algorithm Two.  Algorithm One is the older fairly limited algorithm which has been implemented
4768for completeness.  Algorithm Two is a bit more modern and more flexible to work with.
4769
4770\subsection{Algorithm One}
4771Algorithm One accepts as input a password, an 8--byte salt, and an iteration counter.  The iteration counter is meant to act as delay for
4772people trying to brute force guess the password.  The higher the iteration counter the longer the delay.  This algorithm also requires a hash
4773algorithm and produces an output no longer than the output of the hash.
4774
4775\index{pkcs\_5\_alg1()}
4776\begin{alltt}
4777int pkcs_5_alg1(const unsigned char *password,
4778                      unsigned long  password_len,
4779                const unsigned char *salt,
4780                                int  iteration_count,
4781                                int  hash_idx,
4782                      unsigned char *out,
4783                      unsigned long *outlen)
4784\end{alltt}
4785Where \textit{password} is the user's password.  Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}.
4786The \textit{salt} is a fixed size 8--byte array which should be random for each user and session.  The \textit{iteration\_count} is the delay desired
4787on the password.  The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table.
4788
4789The output of length up to \textit{outlen} is stored in \textit{out}.  If \textit{outlen} is initially larger than the size of the hash functions output
4790it is set to the number of bytes stored.  If it is smaller than not all of the hash output is stored in \textit{out}.
4791
4792\subsection{Algorithm Two}
4793
4794Algorithm Two is the recommended algorithm for this task.  It allows variable length salts, and can produce outputs larger than the
4795hash functions output.  As such, it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required
4796from a single password and invocation of this algorithm.
4797
4798\index{pkcs\_5\_alg2()}
4799\begin{alltt}
4800int pkcs_5_alg2(const unsigned char *password,
4801                      unsigned long  password_len,
4802                const unsigned char *salt,
4803                      unsigned long  salt_len,
4804                                int  iteration_count,
4805                                int  hash_idx,
4806                      unsigned char *out,
4807                      unsigned long *outlen)
4808\end{alltt}
4809Where \textit{password} is the users password.  Since the algorithm allows binary passwords you must also specify the length in \textit{password\_len}.
4810The \textit{salt} is an array of size \textit{salt\_len}.  It should be random for each user and session.  The \textit{iteration\_count} is the delay desired
4811on the password.  The \textit{hash\_idx} is the index of the hash you wish to use in the descriptor table.   The output of length up to
4812\textit{outlen} is stored in \textit{out}.
4813
4814\begin{verbatim}
4815/* demo to show how to make session state material
4816 * from a password */
4817#include <tomcrypt.h>
4818int main(void)
4819{
4820    unsigned char password[100], salt[100],
4821                  cipher_key[16], cipher_iv[16],
4822                  mac_key[16], outbuf[48];
4823    int           err, hash_idx;
4824    unsigned long outlen, password_len, salt_len;
4825
4826    /* register hash and get it's idx .... */
4827
4828    /* get users password and make up a salt ... */
4829
4830    /* create the material (100 iterations in algorithm) */
4831    outlen = sizeof(outbuf);
4832    if ((err = pkcs_5_alg2(password, password_len, salt,
4833                           salt_len, 100, hash_idx, outbuf,
4834                           &outlen))
4835       != CRYPT_OK) {
4836       /* error handle */
4837    }
4838
4839    /* now extract it */
4840    memcpy(cipher_key, outbuf, 16);
4841    memcpy(cipher_iv,  outbuf+16, 16);
4842    memcpy(mac_key,    outbuf+32, 16);
4843
4844    /* use material (recall to store the salt in the output) */
4845}
4846\end{verbatim}
4847
4848\chapter{Miscellaneous}
4849\mysection{Base64 Encoding and Decoding}
4850The library provides functions to encode and decode a RFC 1521 base--64 coding scheme.  The characters used in the mappings are:
4851\begin{verbatim}
4852ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
4853\end{verbatim}
4854Those characters are supported in the 7-bit ASCII map, which means they can be used for transport over
4855common e-mail, usenet and HTTP mediums.  The format of an encoded stream is just a literal sequence of ASCII characters
4856where a group of four represent 24-bits of input.  The first four chars of the encoders output is the length of the
4857original input.  After the first four characters is the rest of the message.
4858
4859Often, it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting.  The decoder allows you to
4860put any character (that is not in the above sequence) in between any character of the encoders output.  You may not however,
4861break up the first four characters.
4862
4863To encode a binary string in base64 call:
4864\index{base64\_encode()}  \index{base64\_decode()}
4865\begin{verbatim}
4866int base64_encode(const unsigned char *in,
4867                        unsigned long  len,
4868                        unsigned char *out,
4869                        unsigned long *outlen);
4870\end{verbatim}
4871Where \textit{in} is the binary string and \textit{out} is where the ASCII output is placed.  You must set the value of \textit{outlen} prior
4872to calling this function and it sets the length of the base64 output in \textit{outlen} when it is done.  To decode a base64
4873string call:
4874\begin{verbatim}
4875int base64_decode(const unsigned char *in,
4876                        unsigned long  len,
4877                        unsigned char *out,
4878                        unsigned long *outlen);
4879\end{verbatim}
4880
4881\mysection{Primality Testing}
4882\index{Primality Testing}
4883The library includes primality testing and random prime functions as well.  The primality tester will perform the test in
4884two phases.  First it will perform trial division by the first few primes.  Second it will perform eight rounds of the
4885Rabin-Miller primality testing algorithm.  If the candidate passes both phases it is declared prime otherwise it is declared
4886composite.  No prime number will fail the two phases but composites can.  Each round of the Rabin-Miller algorithm reduces
4887the probability of a pseudo-prime by $1 \over 4$ therefore after sixteen rounds the probability is no more than
4888$\left ( { 1 \over 4 } \right )^{8} = 2^{-16}$.  In practice the probability of error is in fact much lower than that.
4889
4890When making random primes the trial division step is in fact an optimized implementation of \textit{Implementation of Fast RSA Key Generation on Smart Cards}\footnote{Chenghuai Lu, Andre L. M. dos Santos and Francisco R. Pimentel}.
4891In essence a table of machine-word sized residues are kept of a candidate modulo a set of primes.  When the candidate
4892is rejected and ultimately incremented to test the next number the residues are updated without using multi-word precision
4893math operations.  As a result the routine can scan ahead to the next number required for testing with very little work
4894involved.
4895
4896In the event that a composite did make it through it would most likely cause the the algorithm trying to use it to fail.  For
4897instance, in RSA two primes $p$ and $q$ are required.  The order of the multiplicative sub-group (modulo $pq$) is given
4898as $\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
4899will not be able to sign or decrypt messages at all.  Suppose $p$ was prime and $q$ was composite this is just a variation of
4900the multi-prime RSA.  Suppose $q = rs$ for two primes $r$ and $s$ then $\phi(pq) = (p - 1)(r - 1)(s - 1)$ which clearly is
4901not equal to $(p - 1)(rs - 1)$.
4902
4903These are not technically part of the LibTomMath library but this is the best place to document them.
4904To test if a \textit{mp\_int} is prime call:
4905\begin{verbatim}
4906int is_prime(mp_int *N, int *result);
4907\end{verbatim}
4908This puts a one in \textit{result} if the number is probably prime, otherwise it places a zero in it.  It is assumed that if
4909it returns an error that the value in \textit{result} is undefined.  To make
4910a random prime call:
4911\begin{verbatim}
4912int rand_prime(       mp_int *N,
4913               unsigned long len,
4914                  prng_state *prng,
4915                         int  wprng);
4916\end{verbatim}
4917Where \textit{len} is the size of the prime in bytes ($2 \le len \le 256$).  You can set \textit{len} to the negative size you want
4918to 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
4919\textit{len = -128} to the function.  Upon success it will return {\bf CRYPT\_OK} and \textit{N} will contain an integer which
4920is very likely prime.
4921
4922\chapter{Programming Guidelines}
4923
4924\mysection{Secure Pseudo Random Number Generators}
4925Probably the single most vulnerable point of any cryptosystem is the PRNG.  Without one, generating and protecting secrets
4926would be impossible.  The requirement that one be setup correctly is vitally important, and to address this point the library
4927does provide two RNG sources that will address the largest amount of end users as possible.  The \textit{sprng} PRNG provides an easy to
4928access source of entropy for any application on a UNIX (and the like) or Windows computer.
4929
4930However, when the end user is not on one of these platforms, the application developer must address the issue of finding
4931entropy.  This manual is not designed to be a text on cryptography.  I would just like to highlight that when you design
4932a cryptosystem make sure the first problem you solve is getting a fresh source of entropy.
4933
4934\mysection{Preventing Trivial Errors}
4935Two simple ways to prevent trivial errors is to prevent overflows, and to check the return values.  All of the functions
4936which output variable length strings will require you to pass the length of the destination.  If the size of your output
4937buffer is smaller than the output it will report an error.  Therefore, make sure the size you pass is correct!
4938
4939Also, virtually all of the functions return an error code or {\bf CRYPT\_OK}.  You should detect all errors, as simple
4940typos can cause algorithms to fail to work as desired.
4941
4942\mysection{Registering Your Algorithms}
4943To avoid linking and other run--time errors it is important to register the ciphers, hashes and PRNGs you intend to use
4944before you try to use them.  This includes any function which would use an algorithm indirectly through a descriptor table.
4945
4946A neat bonus to the registry system is that you can add external algorithms that are not part of the library without
4947having to hack the library.  For example, suppose you have a hardware specific PRNG on your system.  You could easily
4948write the few functions required plus a descriptor.  After registering your PRNG, all of the library functions that
4949need a PRNG can instantly take advantage of it.  The same applies for ciphers, hashes, and bignum math routines.
4950
4951\mysection{Key Sizes}
4952
4953\subsection{Symmetric Ciphers}
4954For symmetric ciphers, use as large as of a key as possible.  For the most part \textit{bits are cheap} so using a 256--bit key
4955is not a hard thing to do.  As a good rule of thumb do not use a key smaller than 128 bits.
4956
4957\subsection{Asymmetric Ciphers}
4958The following chart gives the work factor for solving a DH/RSA public key using the NFS.  The work factor for a key of order
4959$n$ is estimated to be
4960\begin{equation}
4961e^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}}
4962\end{equation}
4963
4964Note that $n$ is not the bit-length but the magnitude.  For example, for a 1024-bit key $n = 2^{1024}$.  The work required
4965is:
4966\begin{figure}[here]
4967\begin{center}
4968\begin{tabular}{|c|c|}
4969    \hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\
4970    \hline 512 & 63.92 \\
4971    \hline 768 & 76.50 \\
4972    \hline 1024 & 86.76 \\
4973    \hline 1536 & 103.37 \\
4974    \hline 2048 & 116.88 \\
4975    \hline 2560 & 128.47 \\
4976    \hline 3072 & 138.73 \\
4977    \hline 4096 & 156.49 \\
4978    \hline
4979\end{tabular}
4980\end{center}
4981\caption{RSA/DH Key Strength}
4982\end{figure}
4983
4984The work factor for ECC keys is much higher since the best attack is still fully exponential.  Given a key of magnitude
4985$n$ it requires $\sqrt n$ work.  The following table summarizes the work required:
4986\begin{figure}[here]
4987\begin{center}
4988\begin{tabular}{|c|c|}
4989    \hline ECC Key Size (bits) & Work Factor ($log_2$) \\
4990    \hline 112 & 56 \\
4991    \hline 128 & 64 \\
4992    \hline 160 & 80 \\
4993    \hline 192 & 96  \\
4994    \hline 224 & 112 \\
4995    \hline 256 & 128 \\
4996    \hline 384 & 192 \\
4997    \hline 521 & 260.5 \\
4998    \hline
4999\end{tabular}
5000\end{center}
5001\caption{ECC Key Strength}
5002\end{figure}
5003
5004Using the above tables the following suggestions for key sizes seems appropriate:
5005\begin{center}
5006\begin{tabular}{|c|c|c|}
5007    \hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\
5008    \hline Near term   & 1024 & 160 \\
5009    \hline Short term  & 1536 & 192 \\
5010    \hline Long Term   & 2560 & 384 \\
5011    \hline
5012\end{tabular}
5013\end{center}
5014
5015\mysection{Thread Safety}
5016The library is not fully thread safe but several simple precautions can be taken to avoid any problems.  The registry functions
5017such as register\_cipher() are not thread safe no matter what you do.  It is best to call them from your programs initialization
5018code before threads are initiated.
5019
5020The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc.  This means that if each
5021thread has its own state variables then they will not affect each other, and are fully thread safe.  This is fairly simple with symmetric ciphers
5022and hashes.
5023
5024\index{LTC\_PTHREAD}
5025The only sticky issue is a shared PRNG which can be alleviated with the careful use of mutex devices.  Defining LTC\_PTHREAD for instance, enables
5026pthreads based mutex locking in various routines such as the Yarrow and Fortuna PRNGs, the fixed point ECC multiplier, and other routines.
5027
5028\chapter{Configuring and Building the Library}
5029\mysection{Introduction}
5030The library is fairly flexible about how it can be built, used, and generally distributed.  Additions are being made with
5031each new release that will make the library even more flexible.  Each of the classes of functions can be disabled during
5032the build process to make a smaller library.  This is particularly useful for shared libraries.
5033
5034As of v1.06 of the library, the build process has been moved to two steps for the typical LibTomCrypt application.  This is because
5035LibTomCrypt no longer provides a math API on its own and relies on third party libraries (such as LibTomMath, GnuMP, or TomsFastMath).
5036
5037The build process now consists of installing a math library first, and then building and installing LibTomCrypt with a math library
5038configured.  Note that LibTomCrypt can be built with no internal math descriptors.  This means that one must be provided at either
5039build, or run time for the application.  LibTomCrypt comes with three math descriptors that provide a standard interface to math
5040libraries.
5041
5042\mysection{Makefile variables}
5043
5044All GNU driven makefiles (including the makefile for ICC) use a set of common variables to control the build and install process.  Most of the
5045settings can be overwritten from the command line which makes custom installation a breeze.
5046
5047\index{MAKE}\index{CC}\index{AR}
5048\subsection{MAKE, CC and AR}
5049The MAKE, CC and AR flags can all be overwritten.  They default to \textit{make}, \textit{\$CC} and \textit{\$AR} respectively.
5050Changing MAKE allows you to change what program will be invoked to handle sub--directories. For example, this
5051
5052\begin{verbatim}
5053MAKE=gmake gmake install
5054\end{verbatim}
5055
5056\begin{flushleft} will build and install the libraries with the \textit{gmake} tool.  Similarly, \end{flushleft}
5057
5058\begin{verbatim}
5059CC=arm-gcc AR=arm-ar make
5060\end{verbatim}
5061
5062\begin{flushleft} will build the library using \textit{arm--gcc} as the compiler and \textit{arm--ar} as the archiver. \end{flushleft}
5063
5064\subsection{IGNORE\_SPEED}
5065\index{IGNORE\_SPEED}
5066When \textbf{IGNORE\_SPEED} has been defined the default optimization flags for CFLAGS will be disabled which allows the developer to specify new
5067CFLAGS on the command line.  E.g. to add debugging
5068
5069\begin{verbatim}
5070CFLAGS="-g3" make IGNORE_SPEED=1
5071\end{verbatim}
5072
5073This will turn off optimizations and add \textit{-g3} to the CFLAGS which enables debugging.
5074
5075\subsection{LIBNAME and LIBNAME\_S}
5076\index{LIBNAME} \index{LIBNAME\_S}
5077\textbf{LIBNAME} is the name of the output library (archive) to create.  It defaults to \textit{libtomcrypt.a} for static builds and \textit{libtomcrypt.la} for
5078shared.  The \textbf{LIBNAME\_S} variable is the static name while doing shared builds.  Ideally they should have the same prefix but don't have to.
5079
5080\index{LIBTEST} \index{LIBTEST\_S}
5081Similarly \textbf{LIBTEST} and \textbf{LIBTEST\_S} are the names for the profiling and testing library.  The default is \textit{libtomcrypt\_prof.a} for
5082static and \textit{libtomcrypt\_prof.la} for shared.
5083
5084\subsection{Installation Directories}
5085\index{DESTDIR} \index{LIBPATH} \index{INCPATH} \index{DATADIR}
5086\textbf{DESTDIR} is the prefix for the installation directories.  It defaults to an empty string.  \textbf{LIBPATH} is the prefix for the library
5087directory which defaults to \textit{/usr/lib}.  \textbf{INCPATH} is the prefix for the header file directory which defaults to \textit{/usr/include}.
5088\textbf{DATADIR} is the prefix for the data (documentation) directory which defaults to \textit{/usr/share/doc/libtomcrypt/pdf}.
5089
5090All four can be used to create custom install locations depending on the nature of the OS and file system in use.
5091
5092\begin{verbatim}
5093make LIBPATH=/home/tom/project/lib INCPATH=/home/tom/project/include \
5094     DATAPATH=/home/tom/project/docs install
5095\end{verbatim}
5096
5097This will build the library and install it to the directories under \textit{/home/tom/project/}.  e.g.
5098
5099\begin{small}
5100\begin{verbatim}
5101/home/tom/project/:
5102total 1
5103drwxr-xr-x  2 tom users  80 Jul 30 16:02 docs
5104drwxr-xr-x  2 tom users 528 Jul 30 16:02 include
5105drwxr-xr-x  2 tom users  80 Jul 30 16:02 lib
5106
5107/home/tom/project/docs:
5108total 452
5109-rwxr-xr-x  1 tom users 459009 Jul 30 16:02 crypt.pdf
5110
5111/home/tom/project/include:
5112total 132
5113-rwxr-xr-x  1 tom users  2482 Jul 30 16:02 tomcrypt.h
5114-rwxr-xr-x  1 tom users   702 Jul 30 16:02 tomcrypt_argchk.h
5115-rwxr-xr-x  1 tom users  2945 Jul 30 16:02 tomcrypt_cfg.h
5116-rwxr-xr-x  1 tom users 22763 Jul 30 16:02 tomcrypt_cipher.h
5117-rwxr-xr-x  1 tom users  5174 Jul 30 16:02 tomcrypt_custom.h
5118-rwxr-xr-x  1 tom users 11314 Jul 30 16:02 tomcrypt_hash.h
5119-rwxr-xr-x  1 tom users 11571 Jul 30 16:02 tomcrypt_mac.h
5120-rwxr-xr-x  1 tom users 13614 Jul 30 16:02 tomcrypt_macros.h
5121-rwxr-xr-x  1 tom users 14714 Jul 30 16:02 tomcrypt_math.h
5122-rwxr-xr-x  1 tom users   632 Jul 30 16:02 tomcrypt_misc.h
5123-rwxr-xr-x  1 tom users 10934 Jul 30 16:02 tomcrypt_pk.h
5124-rwxr-xr-x  1 tom users  2634 Jul 30 16:02 tomcrypt_pkcs.h
5125-rwxr-xr-x  1 tom users  7067 Jul 30 16:02 tomcrypt_prng.h
5126-rwxr-xr-x  1 tom users  1467 Jul 30 16:02 tomcrypt_test.h
5127
5128/home/tom/project/lib:
5129total 1073
5130-rwxr-xr-x  1 tom users 1096284 Jul 30 16:02 libtomcrypt.a
5131\end{verbatim}
5132\end{small}
5133
5134\mysection{Extra libraries}
5135\index{EXTRALIBS}
5136\textbf{EXTRALIBS} specifies any extra libraries required to link the test programs and shared libraries.  They are specified in the notation
5137that GCC expects for global archives.
5138
5139\begin{verbatim}
5140CFLAGS="-DTFM_DESC -DUSE_TFM" EXTRALIBS=-ltfm make install \
5141                                                   test timing
5142\end{verbatim}
5143
5144This will install the library using the TomsFastMath library and link the \textit{libtfm.a} library out of the default library search path.  The two
5145defines are explained below.  You can specify multiple archives (say if you want to support two math libraries, or add on additional code) to
5146the \textbf{EXTRALIBS} variable by separating them by a space.
5147
5148Note that \textbf{EXTRALIBS} is not required if you are only making and installing the static library but none of the test programs.
5149
5150\mysection{Building a Static Library}
5151
5152Building a static library is fairly trivial as it only requires one invocation of the GNU make command.
5153
5154\begin{verbatim}
5155CFLAGS="-DTFM_DESC" make install
5156\end{verbatim}
5157
5158That will build LibTomCrypt (including the TomsFastMath descriptor), and install it in the default locations indicated previously.  You can enable
5159the built--in LibTomMath descriptor as well (or in place of the TomsFastMath descriptor).  Similarly, you can build the library with no built--in
5160math descriptors.
5161
5162\begin{verbatim}
5163make install
5164\end{verbatim}
5165
5166In this case, no math descriptors are present in the library and they will have to be made available at build or run time before you can use any of the
5167public key functions.
5168
5169Note that even if you include the built--in descriptors you must link against the source library as well.
5170
5171\begin{verbatim}
5172gcc -DTFM_DESC myprogram.c -ltomcrypt -ltfm -o myprogram
5173\end{verbatim}
5174
5175This will compile \textit{myprogram} and link it against the LibTomCrypt library as well as TomsFastMath (which must have been previously installed).  Note that
5176we define \textbf{TFM\_DESC} for compilation.  This is so that the TFM descriptor symbol will be defined for the client application to make use of without
5177giving warnings.
5178
5179\mysection{Building a Shared Library}
5180
5181LibTomCrypt can also be built as a shared library through the \textit{makefile.shared} make script.  It is similar to use as the static script except
5182that you \textbf{must} specify the \textbf{EXTRALIBS} variable at install time.
5183
5184\begin{verbatim}
5185CFLAGS="-DTFM_DESC" EXTRALIBS=-ltfm make -f makefile.shared install
5186\end{verbatim}
5187
5188This will build and install the library and link the shared object against the TomsFastMath library (which must be installed as a shared object as well).  The
5189shared build process requires libtool to be installed.
5190
5191\mysection{Header Configuration}
5192The file \textit{tomcrypt\_cfg.h} is what lets you control various high level macros which control the behaviour of the library.  Build options are also
5193stored in \textit{tomcrypt\_custom.h} which allow the enabling and disabling of various algorithms.
5194
5195\subsubsection{ARGTYPE}
5196This lets you control how the LTC\_ARGCHK macro will behave.  The macro is used to check pointers inside the functions against
5197NULL.  There are four settings for ARGTYPE.  When set to 0, it will have the default behaviour of printing a message to
5198stderr and raising a SIGABRT signal.  This is provided so all platforms that use LibTomCrypt can have an error that functions
5199similarly.  When set to 1, it will simply pass on to the assert() macro.  When set to 2, the macro will display the error to
5200stderr then return execution to the caller.  This could lead to a segmentation fault (e.g. when a pointer is \textbf{NULL}) but is useful
5201if you handle signals on your own.  When set to 3, it will resolve to a empty macro and no error checking will be performed.  Finally, when set
5202to 4, it will return CRYPT\_INVALID\_ARG to the caller.
5203
5204\subsubsection{Endianess}
5205There are five macros related to endianess issues.  For little endian platforms define, \textbf{ENDIAN\_LITTLE}.  For big endian
5206platforms define \textbf{ENDIAN\_BIG}.  Similarly when the default word size of an \textit{unsigned long} is 32-bits define \textbf{ENDIAN\_32BITWORD}
5207or define \textbf{ENDIAN\_64BITWORD} when its 64-bits.  If you do not define any of them the library will automatically use \textbf{ENDIAN\_NEUTRAL}
5208which will work on all platforms.
5209
5210Currently LibTomCrypt will detect x86-32, x86-64, MIPS R5900, SPARC and SPARC64 running GCC as well as x86-32 running MSVC.
5211
5212\mysection{The Configure Script}
5213There are also options you can specify from the \textit{tomcrypt\_custom.h} header file.
5214
5215\subsection{X memory routines}
5216\index{XMALLOC}\index{XCALLOC}\index{XREALLOC}\index{XFREE}
5217At the top of tomcrypt\_custom.h are a series of macros denoted as XMALLOC, XCALLOC, XREALLOC, XFREE, and so on.  They resolve to
5218the name of the respective functions from the standard C library by default.  This lets you substitute in your own memory routines.
5219If you substitute in your own functions they must behave like the standard C library functions in terms of what they expect as input and
5220output.
5221
5222These macros are handy for working with platforms which do not have a standard C library.  For instance, the OLPC\footnote{See http://dev.laptop.org/git?p=bios-crypto;a=summary}
5223bios code uses these macros to redirect to very compact heap and string operations.
5224
5225\subsection{X clock routines}
5226The rng\_get\_bytes() function can call a function that requires the clock() function.  These macros let you override
5227the default clock() used with a replacement.  By default the standard C library clock() function is used.
5228
5229\subsection{LTC\_NO\_FILE}
5230During the build if LTC\_NO\_FILE is defined then any function in the library that uses file I/O will not call the file I/O
5231functions and instead simply return CRYPT\_NOP.  This should help resolve any linker errors stemming from a lack of
5232file I/O on embedded platforms.
5233
5234\subsection{LTC\_CLEAN\_STACK}
5235When this functions is defined the functions that store key material on the stack will clean up afterwards.
5236Assumes that you have no memory paging with the stack.
5237
5238\subsection{LTC\_TEST}
5239When this has been defined the various self--test functions (for ciphers, hashes, prngs, etc) are included in the build.  This is the default configuration.
5240If LTC\_NO\_TEST has been defined, the testing routines will be compacted and only return CRYPT\_NOP.
5241
5242\subsection{LTC\_NO\_FAST}
5243When this has been defined the library will not use faster word oriented operations.  By default, they are only enabled for platforms
5244which can be auto-detected.  This macro ensures that they are never enabled.
5245
5246\subsection{LTC\_FAST}
5247This mode (auto-detected with x86\_32,x86\_64 platforms with GCC or MSVC) configures various routines such as ctr\_encrypt() or
5248cbc\_encrypt() that it can safely XOR multiple octets in one step by using a larger data type.  This has the benefit of
5249cutting down the overhead of the respective functions.
5250
5251This mode does have one downside.  It can cause unaligned reads from memory if you are not careful with the functions.  This is why
5252it has been enabled by default only for the x86 class of processors where unaligned accesses are allowed.  Technically LTC\_FAST
5253is not \textit{portable} since unaligned accesses are not covered by the ISO C specifications.
5254
5255In practice however, you can use it on pretty much any platform (even MIPS) with care.
5256
5257By design the \textit{fast} mode functions won't get unaligned on their own.  For instance, if you call ctr\_encrypt() right after calling
5258ctr\_start() and all the inputs you gave are aligned than ctr\_encrypt() will perform aligned memory operations only.  However, if you
5259call ctr\_encrypt() with an odd amount of plaintext then call it again the CTR pad (the IV) will be partially used.  This will
5260cause the ctr routine to first use up the remaining pad bytes.  Then if there are enough plaintext bytes left it will use
5261whole word XOR operations.  These operations will be unaligned.
5262
5263The simplest precaution is to make sure you process all data in power of two blocks and handle \textit{remainder} at the end.  e.g. If you are
5264CTR'ing a long stream process it in blocks of (say) four kilobytes and handle any remaining incomplete blocks at the end of the stream.
5265
5266\index{LTC\_FAST\_TYPE}
5267If you do plan on using the \textit{LTC\_FAST} mode you have to also define a \textit{LTC\_FAST\_TYPE} macro which resolves to an optimal sized
5268data type you can perform integer operations with.  Ideally it should be four or eight bytes since it must properly divide the size
5269of your block cipher (e.g. 16 bytes for AES).  This means sadly if you're on a platform with 57--bit words (or something) you can't
5270use this mode.  So sad.
5271
5272\subsection{LTC\_NO\_ASM}
5273When this has been defined the library will not use any inline assembler.  Only a few platforms support assembler inlines but various versions of ICC and GCC
5274cannot handle all of the assembler functions.
5275
5276\subsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions}
5277There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly
5278self-explanatory.  When they are defined the functionality is included otherwise it is not.  There are some
5279dependency issues which are noted in the file.  For instance, Yarrow requires CTR chaining mode, a block
5280cipher and a hash function.
5281
5282Also see technical note number five for more details.
5283
5284\subsection{LTC\_EASY}
5285When defined the library is configured to build fewer algorithms and modes.  Mostly it sticks to NIST and ANSI approved algorithms.  See
5286the header file \textit{tomcrypt\_custom.h} for more details.  It is meant to provide literally an easy method of trimming the library
5287build to the most minimum of useful functionality.
5288
5289\subsection{TWOFISH\_SMALL and TWOFISH\_TABLES}
5290Twofish is a 128-bit symmetric block cipher that is provided within the library.  The cipher itself is flexible enough
5291to allow some trade-offs in the implementation.  When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish
5292requires only 200 bytes of memory.  This is achieved by not pre-computing the substitution boxes.  Having this
5293defined will also greatly slow down the cipher.  When this macro is not defined Twofish will pre-compute the
5294tables at a cost of 4KB of memory.  The cipher will be much faster as a result.
5295
5296When TWOFISH\_TABLES is defined the cipher will use pre-computed (and fixed in code) tables required to work.  This is
5297useful when TWOFISH\_SMALL is defined as the table values are computed on the fly.  When this is defined the code size
5298will increase by approximately 500 bytes.  If this is defined but TWOFISH\_SMALL is not the cipher will still work but
5299it will not speed up the encryption or decryption functions.
5300
5301\subsection{GCM\_TABLES}
5302When defined GCM will use a 64KB table (per GCM state) which will greatly speed up the per--packet latency.
5303It also increases the initialization time and is not suitable when you are going to use a key a few times only.
5304
5305\subsection{GCM\_TABLES\_SSE2}
5306\index{SSE2}
5307When defined GCM will use the SSE2 instructions to perform the $GF(2^x)$ multiply using 16 128--bit XOR operations.  It shaves a few cycles per byte
5308of GCM output on both the AMD64 and Intel Pentium 4 platforms.  Requires GCC and an SSE2 equipped platform.
5309
5310\subsection{LTC\_SMALL\_CODE}
5311When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants.
5312These variants are slower but can save quite a bit of code space.
5313
5314\subsection{LTC\_PTHREAD}
5315When this is activated all of the descriptor table functions will use pthread locking to ensure thread safe updates to the tables.  Note that
5316it doesn't prevent a thread that is passively using a table from being messed up by another thread that updates the table.
5317
5318Generally the rule of thumb is to setup the tables once at startup and then leave them be.  This added build flag simply makes updating
5319the tables safer.
5320
5321\subsection{LTC\_ECC\_TIMING\_RESISTANT}
5322When this has been defined the ECC point multiplier (built--in to the library) will use a timing resistant point multiplication
5323algorithm which prevents leaking key bits of the private key (scalar).  It is a slower algorithm but useful for situations
5324where timing side channels pose a significant threat.
5325
5326\subsection{Math Descriptors}
5327The library comes with three math descriptors that allow you to interface the public key cryptography API to freely available math
5328libraries.  When \textbf{GMP\_DESC}, \textbf{LTM\_DESC}, or \textbf{TFM\_DESC} are defined
5329descriptors for the respective library are built and included in the library as \textit{gmp\_desc}, \textit{ltm\_desc}, or \textit{tfm\_desc} respectively.
5330
5331In the test demos that use the libraries the additional flags \textbf{USE\_GMP}, \textbf{USE\_LTM}, and \textbf{USE\_TFM} can be defined
5332to tell the program which library to use.  Only one of the USE flags can be defined at once.
5333
5334\index{GMP\_DESC} \index{USE\_GMP} \index{LTM\_DESC} \index{TFM\_DESC} \index{USE\_LTM} \index{USE\_TFM}
5335\begin{small}
5336\begin{verbatim}
5337CFLAGS="-DGMP_DESC -DLTM_DESC -DTFM_DESC -DUSE_TFM" \
5338EXTRALIBS="-lgmp -ltommath -ltfm" make -f makefile.shared install timing
5339\end{verbatim}
5340\end{small}
5341
5342That will build and install the library with all descriptors (and link against all), but only use TomsFastMath in the timing demo.
5343
5344\chapter{Optimizations}
5345\mysection{Introduction}
5346The entire API was designed with plug and play in mind at the low level.  That is you can swap out any cipher, hash, PRNG or bignum library and the dependent API will not
5347require updating.  This has the nice benefit that one can add ciphers (etc.) not have to re--write portions of the API.  For the most part, LibTomCrypt has also been written
5348to be highly portable and easy to build out of the box on pretty much any platform.  As such there are no assembler inlines throughout the code, I make no assumptions
5349about the platform, etc...
5350
5351That works well for most cases but there are times where performance is of the essence.  This API allows optimized routines to be dropped in--place of the existing
5352portable routines.  For instance, hand optimized assembler versions of AES could be provided.  Any existing function that uses the cipher could automatically use
5353the optimized code without re--writing.  This also paves the way for hardware drivers that can access hardware accelerated cryptographic devices.
5354
5355At the heart of this flexibility is the \textit{descriptor} system.  A descriptor is essentially just a C \textit{struct} which describes the algorithm and provides pointers
5356to functions that do the required work.  For a given class of operation (e.g. cipher, hash, prng, bignum) the functions of a descriptor have identical prototypes which makes
5357development simple.  In most dependent routines all an end developer has to do is register\_XXX() the descriptor and they are set.
5358
5359\mysection{Ciphers}
5360The ciphers in LibTomCrypt are accessed through the ltc\_cipher\_descriptor structure.
5361
5362\label{sec:cipherdesc}
5363\begin{small}
5364\begin{verbatim}
5365struct ltc_cipher_descriptor {
5366   /** name of cipher */
5367   char *name;
5368
5369   /** internal ID */
5370   unsigned char ID;
5371
5372   /** min keysize (octets) */
5373   int  min_key_length,
5374
5375   /** max keysize (octets) */
5376        max_key_length,
5377
5378   /** block size (octets) */
5379        block_length,
5380
5381   /** default number of rounds */
5382        default_rounds;
5383
5384   /** Setup the cipher
5385      @param key         The input symmetric key
5386      @param keylen      The length of the input key (octets)
5387      @param num_rounds  The requested number of rounds (0==default)
5388      @param skey        [out] The destination of the scheduled key
5389      @return CRYPT_OK if successful
5390   */
5391   int  (*setup)(const unsigned char *key,
5392                                 int  keylen,
5393                                 int  num_rounds,
5394                       symmetric_key *skey);
5395
5396   /** Encrypt a block
5397      @param pt      The plaintext
5398      @param ct      [out] The ciphertext
5399      @param skey    The scheduled key
5400      @return CRYPT_OK if successful
5401   */
5402   int (*ecb_encrypt)(const unsigned char *pt,
5403                            unsigned char *ct,
5404                            symmetric_key *skey);
5405
5406   /** Decrypt a block
5407      @param ct      The ciphertext
5408      @param pt      [out] The plaintext
5409      @param skey    The scheduled key
5410      @return CRYPT_OK if successful
5411   */
5412   int (*ecb_decrypt)(const unsigned char *ct,
5413                            unsigned char *pt,
5414                            symmetric_key *skey);
5415
5416   /** Test the block cipher
5417       @return CRYPT_OK if successful,
5418               CRYPT_NOP if self-testing has been disabled
5419   */
5420   int (*test)(void);
5421
5422   /** Terminate the context
5423      @param skey    The scheduled key
5424   */
5425   void (*done)(symmetric_key *skey);
5426
5427   /** Determine a key size
5428       @param keysize    [in/out] The size of the key desired
5429                                  The suggested size
5430       @return CRYPT_OK if successful
5431   */
5432   int  (*keysize)(int *keysize);
5433
5434/** Accelerators **/
5435   /** Accelerated ECB encryption
5436       @param pt      Plaintext
5437       @param ct      Ciphertext
5438       @param blocks  The number of complete blocks to process
5439       @param skey    The scheduled key context
5440       @return CRYPT_OK if successful
5441   */
5442   int (*accel_ecb_encrypt)(const unsigned char *pt,
5443                                  unsigned char *ct,
5444                                  unsigned long  blocks,
5445                                  symmetric_key *skey);
5446
5447   /** Accelerated ECB decryption
5448       @param pt      Plaintext
5449       @param ct      Ciphertext
5450       @param blocks  The number of complete blocks to process
5451       @param skey    The scheduled key context
5452       @return CRYPT_OK if successful
5453   */
5454   int (*accel_ecb_decrypt)(const unsigned char *ct,
5455                                  unsigned char *pt,
5456                                  unsigned long  blocks,
5457                                  symmetric_key *skey);
5458
5459   /** Accelerated CBC encryption
5460       @param pt      Plaintext
5461       @param ct      Ciphertext
5462       @param blocks  The number of complete blocks to process
5463       @param IV      The initial value (input/output)
5464       @param skey    The scheduled key context
5465       @return CRYPT_OK if successful
5466   */
5467   int (*accel_cbc_encrypt)(const unsigned char *pt,
5468                                  unsigned char *ct,
5469                                  unsigned long  blocks,
5470                                  unsigned char *IV,
5471                                  symmetric_key *skey);
5472
5473   /** Accelerated CBC decryption
5474       @param pt      Plaintext
5475       @param ct      Ciphertext
5476       @param blocks  The number of complete blocks to process
5477       @param IV      The initial value (input/output)
5478       @param skey    The scheduled key context
5479       @return CRYPT_OK if successful
5480   */
5481   int (*accel_cbc_decrypt)(const unsigned char *ct,
5482                                  unsigned char *pt,
5483                                  unsigned long  blocks,
5484                                  unsigned char *IV,
5485                                  symmetric_key *skey);
5486
5487   /** Accelerated CTR encryption
5488       @param pt      Plaintext
5489       @param ct      Ciphertext
5490       @param blocks  The number of complete blocks to process
5491       @param IV      The initial value (input/output)
5492       @param mode    little or big endian counter (mode=0 or mode=1)
5493       @param skey    The scheduled key context
5494       @return CRYPT_OK if successful
5495   */
5496   int (*accel_ctr_encrypt)(const unsigned char *pt,
5497                                  unsigned char *ct,
5498                                  unsigned long  blocks,
5499                                  unsigned char *IV,
5500                                            int  mode,
5501                                  symmetric_key *skey);
5502
5503   /** Accelerated LRW
5504       @param pt      Plaintext
5505       @param ct      Ciphertext
5506       @param blocks  The number of complete blocks to process
5507       @param IV      The initial value (input/output)
5508       @param tweak   The LRW tweak
5509       @param skey    The scheduled key context
5510       @return CRYPT_OK if successful
5511   */
5512   int (*accel_lrw_encrypt)(const unsigned char *pt,
5513                                  unsigned char *ct,
5514                                  unsigned long  blocks,
5515                                  unsigned char *IV,
5516                            const unsigned char *tweak,
5517                                  symmetric_key *skey);
5518
5519   /** Accelerated LRW
5520       @param ct      Ciphertext
5521       @param pt      Plaintext
5522       @param blocks  The number of complete blocks to process
5523       @param IV      The initial value (input/output)
5524       @param tweak   The LRW tweak
5525       @param skey    The scheduled key context
5526       @return CRYPT_OK if successful
5527   */
5528   int (*accel_lrw_decrypt)(const unsigned char *ct,
5529                                  unsigned char *pt,
5530                                  unsigned long  blocks,
5531                                  unsigned char *IV,
5532                            const unsigned char *tweak,
5533                                  symmetric_key *skey);
5534
5535   /** Accelerated CCM packet (one-shot)
5536       @param key        The secret key to use
5537       @param keylen     The length of the secret key (octets)
5538       @param uskey      A previously scheduled key [can be NULL]
5539       @param nonce      The session nonce [use once]
5540       @param noncelen   The length of the nonce
5541       @param header     The header for the session
5542       @param headerlen  The length of the header (octets)
5543       @param pt         [out] The plaintext
5544       @param ptlen      The length of the plaintext (octets)
5545       @param ct         [out] The ciphertext
5546       @param tag        [out] The destination tag
5547       @param taglen     [in/out] The max size and resulting size
5548                                  of the authentication tag
5549       @param direction  Encrypt or Decrypt direction (0 or 1)
5550       @return CRYPT_OK if successful
5551   */
5552   int (*accel_ccm_memory)(
5553       const unsigned char *key,    unsigned long keylen,
5554       symmetric_key       *uskey,
5555       const unsigned char *nonce,  unsigned long noncelen,
5556       const unsigned char *header, unsigned long headerlen,
5557             unsigned char *pt,     unsigned long ptlen,
5558             unsigned char *ct,
5559             unsigned char *tag,    unsigned long *taglen,
5560                       int  direction);
5561
5562   /** Accelerated GCM packet (one shot)
5563       @param key        The secret key
5564       @param keylen     The length of the secret key
5565       @param IV         The initial vector
5566       @param IVlen      The length of the initial vector
5567       @param adata      The additional authentication data (header)
5568       @param adatalen   The length of the adata
5569       @param pt         The plaintext
5570       @param ptlen      The length of the plaintext/ciphertext
5571       @param ct         The ciphertext
5572       @param tag        [out] The MAC tag
5573       @param taglen     [in/out] The MAC tag length
5574       @param direction  Encrypt or Decrypt mode (GCM_ENCRYPT or GCM_DECRYPT)
5575       @return CRYPT_OK on success
5576   */
5577   int (*accel_gcm_memory)(
5578       const unsigned char *key,    unsigned long keylen,
5579       const unsigned char *IV,     unsigned long IVlen,
5580       const unsigned char *adata,  unsigned long adatalen,
5581             unsigned char *pt,     unsigned long ptlen,
5582             unsigned char *ct,
5583             unsigned char *tag,    unsigned long *taglen,
5584                       int direction);
5585
5586   /** Accelerated one shot OMAC
5587       @param key            The secret key
5588       @param keylen         The key length (octets)
5589       @param in             The message
5590       @param inlen          Length of message (octets)
5591       @param out            [out] Destination for tag
5592       @param outlen         [in/out] Initial and final size of out
5593       @return CRYPT_OK on success
5594   */
5595   int (*omac_memory)(
5596       const unsigned char *key, unsigned long keylen,
5597       const unsigned char *in,  unsigned long inlen,
5598             unsigned char *out, unsigned long *outlen);
5599
5600   /** Accelerated one shot XCBC
5601       @param key            The secret key
5602       @param keylen         The key length (octets)
5603       @param in             The message
5604       @param inlen          Length of message (octets)
5605       @param out            [out] Destination for tag
5606       @param outlen         [in/out] Initial and final size of out
5607       @return CRYPT_OK on success
5608   */
5609   int (*xcbc_memory)(
5610       const unsigned char *key, unsigned long keylen,
5611       const unsigned char *in,  unsigned long inlen,
5612             unsigned char *out, unsigned long *outlen);
5613
5614   /** Accelerated one shot F9
5615       @param key            The secret key
5616       @param keylen         The key length (octets)
5617       @param in             The message
5618       @param inlen          Length of message (octets)
5619       @param out            [out] Destination for tag
5620       @param outlen         [in/out] Initial and final size of out
5621       @return CRYPT_OK on success
5622       @remark Requires manual padding
5623   */
5624   int (*f9_memory)(
5625       const unsigned char *key, unsigned long keylen,
5626       const unsigned char *in,  unsigned long inlen,
5627             unsigned char *out, unsigned long *outlen);
5628};
5629\end{verbatim}
5630\end{small}
5631
5632\subsection{Name}
5633\index{find\_cipher()}
5634The \textit{name} parameter specifies the name of the cipher.  This is what a developer would pass to find\_cipher() to find the cipher in the descriptor
5635tables.
5636
5637\subsection{Internal ID}
5638This is a single byte Internal ID you can use to distinguish ciphers from each other.
5639
5640\subsection{Key Lengths}
5641The minimum key length is \textit{min\_key\_length} and is measured in octets.  Similarly the maximum key length is \textit{max\_key\_length}.  They can be equal
5642and both must valid key sizes for the cipher.  Values in between are not assumed to be valid though they may be.
5643
5644\subsection{Block Length}
5645The size of the ciphers plaintext or ciphertext is \textit{block\_length} and is measured in octets.
5646
5647\subsection{Rounds}
5648Some ciphers allow different number of rounds to be used.  Usually you just use the default.  The default round count is \textit{default\_rounds}.
5649
5650\subsection{Setup}
5651To initialize a cipher (for ECB mode) the function setup() was provided.  It accepts an array of key octets \textit{key} of length \textit{keylen} octets.  The user
5652can specify the number of rounds they want through \textit{num\_rounds} where $num\_rounds = 0$ means use the default.  The destination of a scheduled key is stored
5653in \textit{skey}.
5654
5655Inside the \textit{symmetric\_key} union there is a \textit{void *data} which you can use to allocate data if you need a data structure that does not fit with the existing
5656ones provided.  Just make sure in your \textit{done()} function that you free the allocated memory.
5657
5658\subsection{Single block ECB}
5659To process a single block in ECB mode the ecb\_encrypt() and ecb\_decrypt() functions were provided.  The plaintext and ciphertext buffers are allowed to overlap so you
5660must make sure you do not overwrite the output before you are finished with the input.
5661
5662\subsection{Testing}
5663The test() function is used to self--test the \textit{device}.  It takes no arguments and returns \textbf{CRYPT\_OK} if all is working properly.  You may return
5664\textbf{CRYPT\_NOP} to indicate that no testing was performed.
5665
5666\subsection{Key Sizing}
5667Occasionally, a function will want to find a suitable key size to use since the input is oddly sized.  The keysize() function is for this case.  It accepts a
5668pointer to an integer which represents the desired size.  The function then has to match it to the exact or a lower key size that is valid for the cipher.  For
5669example, if the input is $25$ and $24$ is valid then it stores $24$ back in the pointed to integer.  It must not round up and must return an error if the keysize
5670 cannot be mapped to a valid key size for the cipher.
5671
5672\subsection{Acceleration}
5673The next set of functions cover the accelerated functionality of the cipher descriptor.  Any combination of these functions may be set to \textbf{NULL} to indicate
5674it is not supported.  In those cases the software defaults are used (using the single ECB block routines).
5675
5676\subsubsection{Accelerated ECB}
5677These two functions are meant for cases where a user wants to encrypt (in ECB mode no less) an array of blocks.  These functions are accessed
5678through the accel\_ecb\_encrypt and accel\_ecb\_decrypt pointers.  The \textit{blocks} count is the number of complete blocks to process.
5679
5680\subsubsection{Accelerated CBC}
5681These two functions are meant for accelerated CBC encryption.  These functions are accessed through the accel\_cbc\_encrypt and accel\_cbc\_decrypt pointers.
5682The \textit{blocks} value is the number of complete blocks to process.  The \textit{IV} is the CBC initial vector.  It is an input upon calling this function and must be
5683updated by the function before returning.
5684
5685\subsubsection{Accelerated CTR}
5686This function is meant for accelerated CTR encryption.  It is accessible through the accel\_ctr\_encrypt pointer.
5687The \textit{blocks} value is the number of complete blocks to process.  The \textit{IV} is the CTR counter vector.  It is an input upon calling this function and must be
5688updated by the function before returning.  The \textit{mode} value indicates whether the counter is big (mode = CTR\_COUNTER\_BIG\_ENDIAN) or
5689little (mode = CTR\_COUNTER\_LITTLE\_ENDIAN) endian.
5690
5691This function (and the way it's called) differs from the other two since ctr\_encrypt() allows any size input plaintext.  The accelerator will only be
5692called if the following conditions are met.
5693
5694\begin{enumerate}
5695   \item The accelerator is present
5696   \item The CTR pad is empty
5697   \item The remaining length of the input to process is greater than or equal to the block size.
5698\end{enumerate}
5699
5700The \textit{CTR pad} is empty when a multiple (including zero) blocks of text have been processed.  That is, if you pass in seven bytes to AES--CTR mode you would have to
5701pass in a minimum of nine extra bytes before the accelerator could be called.  The CTR accelerator must increment the counter (and store it back into the
5702buffer provided) before encrypting it to create the pad.
5703
5704The accelerator will only be used to encrypt whole blocks.  Partial blocks are always handled in software.
5705
5706\subsubsection{Accelerated LRW}
5707These functions are meant for accelerated LRW.  They process blocks of input in lengths of multiples of 16 octets.  They must accept the \textit{IV} and \textit{tweak}
5708state variables and updated them prior to returning.  Note that you may want to disable \textbf{LRW\_TABLES} in \textit{tomcrypt\_custom.h} if you intend
5709to use accelerators for LRW.
5710
5711While both encrypt and decrypt accelerators are not required it is suggested as it makes lrw\_setiv() more efficient.
5712
5713Note that calling lrw\_done() will only invoke the cipher\_descriptor[].done() function on the \textit{symmetric\_key} parameter of the LRW state.  That means
5714if your device requires any (LRW specific) resources you should free them in your ciphers() done function.  The simplest way to think of it is to write
5715the plugin solely to do LRW with the cipher.  That way cipher\_descriptor[].setup() means to init LRW resources and cipher\_descriptor[].done() means to
5716free them.
5717
5718\subsubsection{Accelerated CCM}
5719This function is meant for accelerated CCM encryption or decryption.  It processes the entire packet in one call.  You can optimize the work flow somewhat
5720by allowing the caller to call the setup() function first to schedule the key if your accelerator cannot do the key schedule on the fly (for instance).  This
5721function MUST support both key passing methods.
5722
5723\begin{center}
5724\begin{small}
5725\begin{tabular}{|r|r|l|}
5726\hline \textbf{key} & \textbf{uskey} & \textbf{Source of key} \\
5727\hline NULL         & NULL           & Error, not supported \\
5728\hline non-NULL     & NULL           & Use key, do a key schedule \\
5729\hline NULL         & non-NULL       & Use uskey, key schedule not required \\
5730\hline non-NULL     & non-NULL       & Use uskey, key schedule not required \\
5731\hline
5732\end{tabular}
5733\end{small}
5734\end{center}
5735
5736\index{ccm\_memory()} This function is called when the user calls ccm\_memory().
5737
5738\subsubsection{Accelerated GCM}
5739\index{gcm\_memory()}
5740This function is meant for accelerated GCM encryption or decryption.  It processes the entire packet in one call.  Note that the setup() function will not
5741be called prior to this.  This function must handle scheduling the key provided on its own.  It is called when the user calls gcm\_memory().
5742
5743\subsubsection{Accelerated OMAC}
5744\index{omac\_memory()}
5745This function is meant to perform an optimized OMAC1 (CMAC) message authentication code computation when the user calls omac\_memory().
5746
5747\subsubsection{Accelerated XCBC-MAC}
5748\index{xcbc\_memory()}
5749This function is meant to perform an optimized XCBC-MAC message authentication code computation when the user calls xcbc\_memory().
5750
5751\subsubsection{Accelerated F9}
5752\index{f9\_memory()}
5753This function is meant to perform an optimized F9 message authentication code computation when the user calls f9\_memory().  Like f9\_memory(), it requires
5754the caller to perform any 3GPP related padding before calling in order to ensure proper compliance with F9.
5755
5756
5757\mysection{One--Way Hashes}
5758The hash functions are accessed through the ltc\_hash\_descriptor structure.
5759
5760\begin{small}
5761\begin{verbatim}
5762struct ltc_hash_descriptor {
5763    /** name of hash */
5764    char *name;
5765
5766    /** internal ID */
5767    unsigned char ID;
5768
5769    /** Size of digest in octets */
5770    unsigned long hashsize;
5771
5772    /** Input block size in octets */
5773    unsigned long blocksize;
5774
5775    /** ASN.1 OID */
5776    unsigned long OID[16];
5777
5778    /** Length of DER encoding */
5779    unsigned long OIDlen;
5780
5781    /** Init a hash state
5782      @param hash   The hash to initialize
5783      @return CRYPT_OK if successful
5784    */
5785    int (*init)(hash_state *hash);
5786
5787    /** Process a block of data
5788      @param hash   The hash state
5789      @param in     The data to hash
5790      @param inlen  The length of the data (octets)
5791      @return CRYPT_OK if successful
5792    */
5793    int (*process)(         hash_state *hash,
5794                   const unsigned char *in,
5795                         unsigned long  inlen);
5796
5797    /** Produce the digest and store it
5798      @param hash   The hash state
5799      @param out    [out] The destination of the digest
5800      @return CRYPT_OK if successful
5801    */
5802    int (*done)(   hash_state *hash,
5803                unsigned char *out);
5804
5805    /** Self-test
5806      @return CRYPT_OK if successful,
5807              CRYPT_NOP if self-tests have been disabled
5808    */
5809    int (*test)(void);
5810
5811    /* accelerated hmac callback: if you need to-do
5812       multiple packets just use the generic hmac_memory
5813       and provide a hash callback
5814    */
5815    int  (*hmac_block)(const unsigned char *key,
5816                             unsigned long  keylen,
5817                       const unsigned char *in,
5818                             unsigned long  inlen,
5819                             unsigned char *out,
5820                             unsigned long *outlen);
5821};
5822\end{verbatim}
5823\end{small}
5824
5825\subsection{Name}
5826This is the name the hash is known by and what find\_hash() will look for.
5827
5828\subsection{Internal ID}
5829This is the internal ID byte used to distinguish the hash from other hashes.
5830
5831\subsection{Digest Size}
5832The \textit{hashsize} variable indicates the length of the output in octets.
5833
5834\subsection{Block Size}
5835The \textit{blocksize} variable indicates the length of input (in octets) that the hash processes in a given
5836invocation.
5837
5838\subsection{OID Identifier}
5839This is the universal ASN.1 Object Identifier for the hash.
5840
5841\subsection{Initialization}
5842The init function initializes the hash and prepares it to process message bytes.
5843
5844\subsection{Process}
5845This processes message bytes.  The algorithm must accept any length of input that the hash would allow.  The input is not
5846guaranteed to be a multiple of the block size in length.
5847
5848\subsection{Done}
5849The done function terminates the hash and returns the message digest.
5850
5851\subsection{Acceleration}
5852A compatible accelerator must allow processing data in any granularity which may require internal padding on the driver side.
5853
5854\subsection{HMAC Acceleration}
5855The hmac\_block() callback is meant for single--shot optimized HMAC implementations.  It is called directly by hmac\_memory() if present.  If you need
5856to be able to process multiple blocks per MAC then you will have to simply provide a process() callback and use hmac\_memory() as provided in LibTomCrypt.
5857
5858\mysection{Pseudo--Random Number Generators}
5859The pseudo--random number generators are accessible through the ltc\_prng\_descriptor structure.
5860
5861\begin{small}
5862\begin{verbatim}
5863struct ltc_prng_descriptor {
5864    /** Name of the PRNG */
5865    char *name;
5866
5867    /** size in bytes of exported state */
5868    int  export_size;
5869
5870    /** Start a PRNG state
5871        @param prng   [out] The state to initialize
5872        @return CRYPT_OK if successful
5873    */
5874    int (*start)(prng_state *prng);
5875
5876    /** Add entropy to the PRNG
5877        @param in         The entropy
5878        @param inlen      Length of the entropy (octets)
5879        @param prng       The PRNG state
5880        @return CRYPT_OK if successful
5881    */
5882    int (*add_entropy)(const unsigned char *in,
5883                             unsigned long  inlen,
5884                                prng_state *prng);
5885
5886    /** Ready a PRNG state to read from
5887        @param prng       The PRNG state to ready
5888        @return CRYPT_OK if successful
5889    */
5890    int (*ready)(prng_state *prng);
5891
5892    /** Read from the PRNG
5893        @param out     [out] Where to store the data
5894        @param outlen  Length of data desired (octets)
5895        @param prng    The PRNG state to read from
5896        @return Number of octets read
5897    */
5898    unsigned long (*read)(unsigned char *out,
5899                          unsigned long  outlen,
5900                             prng_state *prng);
5901
5902    /** Terminate a PRNG state
5903        @param prng   The PRNG state to terminate
5904        @return CRYPT_OK if successful
5905    */
5906    int (*done)(prng_state *prng);
5907
5908    /** Export a PRNG state
5909        @param out     [out] The destination for the state
5910        @param outlen  [in/out] The max size and resulting size
5911        @param prng    The PRNG to export
5912        @return CRYPT_OK if successful
5913    */
5914    int (*pexport)(unsigned char *out,
5915                   unsigned long *outlen,
5916                      prng_state *prng);
5917
5918    /** Import a PRNG state
5919        @param in      The data to import
5920        @param inlen   The length of the data to import (octets)
5921        @param prng    The PRNG to initialize/import
5922        @return CRYPT_OK if successful
5923    */
5924    int (*pimport)(const unsigned char *in,
5925                         unsigned long  inlen,
5926                            prng_state *prng);
5927
5928    /** Self-test the PRNG
5929        @return CRYPT_OK if successful,
5930                CRYPT_NOP if self-testing has been disabled
5931    */
5932    int (*test)(void);
5933};
5934\end{verbatim}
5935\end{small}
5936
5937\subsection{Name}
5938The name by which find\_prng() will find the PRNG.
5939
5940\subsection{Export Size}
5941When an PRNG state is to be exported for future use you specify the space required in this variable.
5942
5943\subsection{Start}
5944Initialize the PRNG and make it ready to accept entropy.
5945
5946\subsection{Entropy Addition}
5947Add entropy to the PRNG state.  The exact behaviour of this function depends on the particulars of the PRNG.
5948
5949\subsection{Ready}
5950This function makes the PRNG ready to read from by processing the entropy added.  The behaviour of this function depends
5951on the specific PRNG used.
5952
5953\subsection{Read}
5954Read from the PRNG and return the number of bytes read.  This function does not have to fill the buffer but it is best
5955if it does as many protocols do not retry reads and will fail on the first try.
5956
5957\subsection{Done}
5958Terminate a PRNG state.  The behaviour of this function depends on the particular PRNG used.
5959
5960\subsection{Exporting and Importing}
5961An exported PRNG state is data that the PRNG can later import to resume activity.  They're not meant to resume \textit{the same session}
5962but should at least maintain the same level of state entropy.
5963
5964\mysection{BigNum Math Descriptors}
5965The library also makes use of the math descriptors to access math functions.  While bignum math libraries usually differ in implementation
5966it hasn't proven hard to write \textit{glue} to use math libraries so far.  The basic descriptor looks like.
5967
5968\begin{small}
5969\begin{verbatim}
5970/** math descriptor */
5971typedef struct {
5972   /** Name of the math provider */
5973   char *name;
5974
5975   /** Bits per digit, amount of bits must fit in an unsigned long */
5976   int  bits_per_digit;
5977
5978/* ---- init/deinit functions ---- */
5979
5980   /** initialize a bignum
5981     @param   a     The number to initialize
5982     @return  CRYPT_OK on success
5983   */
5984   int (*init)(void **a);
5985
5986   /** init copy
5987     @param  dst    The number to initialize and write to
5988     @param  src    The number to copy from
5989     @return CRYPT_OK on success
5990   */
5991   int (*init_copy)(void **dst, void *src);
5992
5993   /** deinit
5994      @param   a    The number to free
5995      @return CRYPT_OK on success
5996   */
5997   void (*deinit)(void *a);
5998
5999/* ---- data movement ---- */
6000
6001   /** copy
6002      @param   src   The number to copy from
6003      @param   dst   The number to write to
6004      @return CRYPT_OK on success
6005   */
6006   int (*copy)(void *src, void *dst);
6007
6008/* ---- trivial low level functions ---- */
6009
6010   /** set small constant
6011      @param a    Number to write to
6012      @param n    Source upto bits_per_digit (meant for small constants)
6013      @return CRYPT_OK on success
6014   */
6015   int (*set_int)(void *a, unsigned long n);
6016
6017   /** get small constant
6018      @param a  Small number to read
6019      @return   The lower bits_per_digit of the integer (unsigned)
6020   */
6021   unsigned long (*get_int)(void *a);
6022
6023   /** get digit n
6024     @param a  The number to read from
6025     @param n  The number of the digit to fetch
6026     @return  The bits_per_digit  sized n'th digit of a
6027   */
6028   unsigned long (*get_digit)(void *a, int n);
6029
6030   /** Get the number of digits that represent the number
6031     @param a   The number to count
6032     @return The number of digits used to represent the number
6033   */
6034   int (*get_digit_count)(void *a);
6035
6036   /** compare two integers
6037     @param a   The left side integer
6038     @param b   The right side integer
6039     @return LTC_MP_LT if a < b,
6040             LTC_MP_GT if a > b and
6041             LTC_MP_EQ otherwise.  (signed comparison)
6042   */
6043   int (*compare)(void *a, void *b);
6044
6045   /** compare against int
6046     @param a   The left side integer
6047     @param b   The right side integer (upto bits_per_digit)
6048     @return LTC_MP_LT if a < b,
6049             LTC_MP_GT if a > b and
6050             LTC_MP_EQ otherwise.  (signed comparison)
6051   */
6052   int (*compare_d)(void *a, unsigned long n);
6053
6054   /** Count the number of bits used to represent the integer
6055     @param a   The integer to count
6056     @return The number of bits required to represent the integer
6057   */
6058   int (*count_bits)(void * a);
6059
6060   /** Count the number of LSB bits which are zero
6061     @param a   The integer to count
6062     @return The number of contiguous zero LSB bits
6063   */
6064   int (*count_lsb_bits)(void *a);
6065
6066   /** Compute a power of two
6067     @param a  The integer to store the power in
6068     @param n  The power of two you want to store (a = 2^n)
6069     @return CRYPT_OK on success
6070   */
6071   int (*twoexpt)(void *a , int n);
6072
6073/* ---- radix conversions ---- */
6074
6075   /** read ascii string
6076     @param a     The integer to store into
6077     @param str   The string to read
6078     @param radix The radix the integer has been represented in (2-64)
6079     @return CRYPT_OK on success
6080   */
6081   int (*read_radix)(void *a, const char *str, int radix);
6082
6083   /** write number to string
6084     @param a     The integer to store
6085     @param str   The destination for the string
6086     @param radix The radix the integer is to be represented in (2-64)
6087     @return CRYPT_OK on success
6088   */
6089   int (*write_radix)(void *a, char *str, int radix);
6090
6091   /** get size as unsigned char string
6092     @param a  The integer to get the size
6093     @return   The length of the integer in octets
6094   */
6095   unsigned long (*unsigned_size)(void *a);
6096
6097   /** store an integer as an array of octets
6098     @param src   The integer to store
6099     @param dst   The buffer to store the integer in
6100     @return CRYPT_OK on success
6101   */
6102   int (*unsigned_write)(void *src, unsigned char *dst);
6103
6104   /** read an array of octets and store as integer
6105     @param dst   The integer to load
6106     @param src   The array of octets
6107     @param len   The number of octets
6108     @return CRYPT_OK on success
6109   */
6110   int (*unsigned_read)(         void *dst,
6111                        unsigned char *src,
6112                        unsigned long  len);
6113
6114/* ---- basic math ---- */
6115
6116   /** add two integers
6117     @param a   The first source integer
6118     @param b   The second source integer
6119     @param c   The destination of "a + b"
6120     @return CRYPT_OK on success
6121   */
6122   int (*add)(void *a, void *b, void *c);
6123
6124   /** add two integers
6125     @param a   The first source integer
6126     @param b   The second source integer
6127               (single digit of upto bits_per_digit in length)
6128     @param c   The destination of "a + b"
6129     @return CRYPT_OK on success
6130   */
6131   int (*addi)(void *a, unsigned long b, void *c);
6132
6133   /** subtract two integers
6134     @param a   The first source integer
6135     @param b   The second source integer
6136     @param c   The destination of "a - b"
6137     @return CRYPT_OK on success
6138   */
6139   int (*sub)(void *a, void *b, void *c);
6140
6141   /** subtract two integers
6142     @param a   The first source integer
6143     @param b   The second source integer
6144                (single digit of upto bits_per_digit in length)
6145     @param c   The destination of "a - b"
6146     @return CRYPT_OK on success
6147   */
6148   int (*subi)(void *a, unsigned long b, void *c);
6149
6150   /** multiply two integers
6151     @param a   The first source integer
6152     @param b   The second source integer
6153                (single digit of upto bits_per_digit in length)
6154     @param c   The destination of "a * b"
6155     @return CRYPT_OK on success
6156   */
6157   int (*mul)(void *a, void *b, void *c);
6158
6159   /** multiply two integers
6160     @param a   The first source integer
6161     @param b   The second source integer
6162                (single digit of upto bits_per_digit in length)
6163     @param c   The destination of "a * b"
6164     @return CRYPT_OK on success
6165   */
6166   int (*muli)(void *a, unsigned long b, void *c);
6167
6168   /** Square an integer
6169     @param a    The integer to square
6170     @param b    The destination
6171     @return CRYPT_OK on success
6172   */
6173   int (*sqr)(void *a, void *b);
6174
6175   /** Divide an integer
6176     @param a    The dividend
6177     @param b    The divisor
6178     @param c    The quotient (can be NULL to signify don't care)
6179     @param d    The remainder (can be NULL to signify don't care)
6180     @return CRYPT_OK on success
6181   */
6182   int (*div)(void *a, void *b, void *c, void *d);
6183
6184   /** divide by two
6185      @param  a   The integer to divide (shift right)
6186      @param  b   The destination
6187      @return CRYPT_OK on success
6188   */
6189   int (*div_2)(void *a, void *b);
6190
6191   /** Get remainder (small value)
6192      @param  a    The integer to reduce
6193      @param  b    The modulus (upto bits_per_digit in length)
6194      @param  c    The destination for the residue
6195      @return CRYPT_OK on success
6196   */
6197   int (*modi)(void *a, unsigned long b, unsigned long *c);
6198
6199   /** gcd
6200      @param  a     The first integer
6201      @param  b     The second integer
6202      @param  c     The destination for (a, b)
6203      @return CRYPT_OK on success
6204   */
6205   int (*gcd)(void *a, void *b, void *c);
6206
6207   /** lcm
6208      @param  a     The first integer
6209      @param  b     The second integer
6210      @param  c     The destination for [a, b]
6211      @return CRYPT_OK on success
6212   */
6213   int (*lcm)(void *a, void *b, void *c);
6214
6215   /** Modular multiplication
6216      @param  a     The first source
6217      @param  b     The second source
6218      @param  c     The modulus
6219      @param  d     The destination (a*b mod c)
6220      @return CRYPT_OK on success
6221   */
6222   int (*mulmod)(void *a, void *b, void *c, void *d);
6223
6224   /** Modular squaring
6225      @param  a     The first source
6226      @param  b     The modulus
6227      @param  c     The destination (a*a mod b)
6228      @return CRYPT_OK on success
6229   */
6230   int (*sqrmod)(void *a, void *b, void *c);
6231
6232   /** Modular inversion
6233      @param  a     The value to invert
6234      @param  b     The modulus
6235      @param  c     The destination (1/a mod b)
6236      @return CRYPT_OK on success
6237   */
6238   int (*invmod)(void *, void *, void *);
6239
6240/* ---- reduction ---- */
6241
6242   /** setup Montgomery
6243       @param a  The modulus
6244       @param b  The destination for the reduction digit
6245       @return CRYPT_OK on success
6246   */
6247   int (*montgomery_setup)(void *a, void **b);
6248
6249   /** get normalization value
6250       @param a   The destination for the normalization value
6251       @param b   The modulus
6252       @return  CRYPT_OK on success
6253   */
6254   int (*montgomery_normalization)(void *a, void *b);
6255
6256   /** reduce a number
6257       @param a   The number [and dest] to reduce
6258       @param b   The modulus
6259       @param c   The value "b" from montgomery_setup()
6260       @return CRYPT_OK on success
6261   */
6262   int (*montgomery_reduce)(void *a, void *b, void *c);
6263
6264   /** clean up  (frees memory)
6265       @param a   The value "b" from montgomery_setup()
6266       @return CRYPT_OK on success
6267   */
6268   void (*montgomery_deinit)(void *a);
6269
6270/* ---- exponentiation ---- */
6271
6272   /** Modular exponentiation
6273       @param a    The base integer
6274       @param b    The power (can be negative) integer
6275       @param c    The modulus integer
6276       @param d    The destination
6277       @return CRYPT_OK on success
6278   */
6279   int (*exptmod)(void *a, void *b, void *c, void *d);
6280
6281   /** Primality testing
6282       @param a     The integer to test
6283       @param b     The destination of the result (FP_YES if prime)
6284       @return CRYPT_OK on success
6285   */
6286   int (*isprime)(void *a, int *b);
6287
6288/* ----  (optional) ecc point math ---- */
6289
6290   /** ECC GF(p) point multiplication (from the NIST curves)
6291       @param k   The integer to multiply the point by
6292       @param G   The point to multiply
6293       @param R   The destination for kG
6294       @param modulus  The modulus for the field
6295       @param map Boolean indicated whether to map back to affine or not
6296                  (can be ignored if you work in affine only)
6297       @return CRYPT_OK on success
6298   */
6299   int (*ecc_ptmul)(     void *k,
6300                    ecc_point *G,
6301                    ecc_point *R,
6302                         void *modulus,
6303                          int  map);
6304
6305   /** ECC GF(p) point addition
6306       @param P    The first point
6307       @param Q    The second point
6308       @param R    The destination of P + Q
6309       @param modulus  The modulus
6310       @param mp   The "b" value from montgomery_setup()
6311       @return CRYPT_OK on success
6312   */
6313   int (*ecc_ptadd)(ecc_point *P,
6314                    ecc_point *Q,
6315                    ecc_point *R,
6316                         void *modulus,
6317                         void *mp);
6318
6319   /** ECC GF(p) point double
6320       @param P    The first point
6321       @param R    The destination of 2P
6322       @param modulus  The modulus
6323       @param mp   The "b" value from montgomery_setup()
6324       @return CRYPT_OK on success
6325   */
6326   int (*ecc_ptdbl)(ecc_point *P,
6327                    ecc_point *R,
6328                         void *modulus,
6329                         void *mp);
6330
6331   /** ECC mapping from projective to affine,
6332       currently uses (x,y,z) => (x/z^2, y/z^3, 1)
6333       @param P     The point to map
6334       @param modulus The modulus
6335       @param mp    The "b" value from montgomery_setup()
6336       @return CRYPT_OK on success
6337       @remark The mapping can be different but keep in mind a
6338               ecc_point only has three integers (x,y,z) so if
6339               you use a different mapping you have to make it fit.
6340   */
6341   int (*ecc_map)(ecc_point *P, void *modulus, void *mp);
6342
6343   /** Computes kA*A + kB*B = C using Shamir's Trick
6344       @param A        First point to multiply
6345       @param kA       What to multiple A by
6346       @param B        Second point to multiply
6347       @param kB       What to multiple B by
6348       @param C        [out] Destination point (can overlap with A or B)
6349       @param modulus  Modulus for curve
6350       @return CRYPT_OK on success
6351   */
6352   int (*ecc_mul2add)(ecc_point *A, void *kA,
6353                      ecc_point *B, void *kB,
6354                      ecc_point *C,
6355                           void *modulus);
6356
6357
6358/* ---- (optional) rsa optimized math (for internal CRT) ---- */
6359
6360   /** RSA Key Generation
6361       @param prng     An active PRNG state
6362       @param wprng    The index of the PRNG desired
6363       @param size     The size of the key in octets
6364       @param e        The "e" value (public key).
6365                       e==65537 is a good choice
6366       @param key      [out] Destination of a newly created private key pair
6367       @return CRYPT_OK if successful, upon error all allocated ram is freed
6368    */
6369    int (*rsa_keygen)(prng_state *prng,
6370                             int  wprng,
6371                             int  size,
6372                            long  e,
6373                         rsa_key *key);
6374
6375   /** RSA exponentiation
6376      @param in       The octet array representing the base
6377      @param inlen    The length of the input
6378      @param out      The destination (to be stored in an octet array format)
6379      @param outlen   The length of the output buffer and the resulting size
6380                      (zero padded to the size of the modulus)
6381      @param which    PK_PUBLIC for public RSA and PK_PRIVATE for private RSA
6382      @param key      The RSA key to use
6383      @return CRYPT_OK on success
6384   */
6385   int (*rsa_me)(const unsigned char *in,   unsigned long inlen,
6386                       unsigned char *out,  unsigned long *outlen, int which,
6387                       rsa_key *key);
6388} ltc_math_descriptor;
6389\end{verbatim}
6390\end{small}
6391
6392Most of the functions are fairly straightforward and do not need documentation.  We'll cover the basic conventions of the API and then explain the accelerated functions.
6393
6394\subsection{Conventions}
6395
6396All \textit{bignums} are accessed through an opaque \textit{void *} data type.  You must internally cast the pointer if you need to access members of your bignum structure.  During
6397the init calls a \textit{void **} will be passed where you allocate your structure and set the pointer then initialize the number to zero.  During the deinit calls you must
6398free the bignum as well as the structure you allocated to place it in.
6399
6400All functions except the Montgomery reductions work from left to right with the arguments.  For example, mul(a, b, c) computes $c \leftarrow ab$.
6401
6402All functions (except where noted otherwise) return \textbf{CRYPT\_OK} to signify a successful operation.  All error codes must be valid LibTomCrypt error codes.
6403
6404The digit routines (including functions with the \textit{i} suffix) use a \textit{unsigned long} to represent the digit.  If your internal digit is larger than this you must
6405then partition your digits.  Normally this does not matter as \textit{unsigned long} will be the same size as your register size.  Note that if your digit is smaller
6406than an \textit{unsigned long} that is also acceptable as the \textit{bits\_per\_digit} parameter will specify this.
6407
6408\subsection{ECC Functions}
6409The ECC system in LibTomCrypt is based off of the NIST recommended curves over $GF(p)$ and is used to implement EC-DSA and EC-DH.   The ECC functions work with
6410the \textbf{ecc\_point} structure and assume the points are stored in Jacobian projective format.
6411
6412\begin{verbatim}
6413/** A point on a ECC curve, stored in Jacobian format such
6414    that (x,y,z) => (x/z^2, y/z^3, 1) when interpreted as affine */
6415typedef struct {
6416    /** The x co-ordinate */
6417    void *x;
6418    /** The y co-ordinate */
6419    void *y;
6420    /** The z co-ordinate */
6421    void *z;
6422} ecc_point;
6423\end{verbatim}
6424
6425All ECC functions must use this mapping system.  The only exception is when you remap all ECC callbacks which will allow you to have more control
6426over how the ECC math will be implemented.  Out of the box you only have three parameters per point to use $(x, y, z)$ however, these are just void pointers.  They
6427could point to anything you want.  The only further exception is the export functions which expects the values to be in affine format.
6428
6429\subsubsection{Point Multiply}
6430This will multiply the point $G$ by the scalar $k$ and store the result in the point $R$.  The value should be mapped to affine only if $map$ is set to one.
6431
6432\subsubsection{Point Addition}
6433This will add the point $P$ to the point $Q$ and store it in the point $R$.  The $mp$ parameter is the \textit{b} value from the montgomery\_setup() call.  The input points
6434may be in either affine (with $z = 1$) or projective format and the output point is always projective.
6435
6436\subsubsection{Point Mapping}
6437This will map the point $P$ back from projective to affine.  The output point $P$ must be of the form $(x, y, 1)$.
6438
6439\subsubsection{Shamir's Trick}
6440\index{Shamir's Trick}
6441\index{ltc\_ecc\_mul2add()}
6442To accelerate EC--DSA verification the library provides a built--in function called ltc\_ecc\_mul2add().  This performs two point multiplications and an addition in
6443roughly the time of one point multiplication.  It is called from ecc\_verify\_hash() if an accelerator is not present.  The acclerator function must allow the points to
6444overlap (e.g., $A \leftarrow k_1A + k_2B$) and must return the final point in affine format.
6445
6446
6447\subsection{RSA Functions}
6448The RSA Modular Exponentiation (ME) function is used by the RSA API to perform exponentiations for private and public key operations.  In particular for
6449private key operations it uses the CRT approach to lower the time required.  It is passed an RSA key with the following format.
6450
6451\begin{verbatim}
6452/** RSA PKCS style key */
6453typedef struct Rsa_key {
6454    /** Type of key, PK_PRIVATE or PK_PUBLIC */
6455    int type;
6456    /** The public exponent */
6457    void *e;
6458    /** The private exponent */
6459    void *d;
6460    /** The modulus */
6461    void *N;
6462    /** The p factor of N */
6463    void *p;
6464    /** The q factor of N */
6465    void *q;
6466    /** The 1/q mod p CRT param */
6467    void *qP;
6468    /** The d mod (p - 1) CRT param */
6469    void *dP;
6470    /** The d mod (q - 1) CRT param */
6471    void *dQ;
6472} rsa_key;
6473\end{verbatim}
6474
6475The call reads the \textit{in} buffer as an unsigned char array in big endian format.  Then it performs the exponentiation and stores the output in big endian format
6476to the \textit{out} buffer.  The output must be zero padded (leading bytes) so that the length of the output matches the length of the modulus (in bytes).  For example,
6477for RSA--1024 the output is always 128 bytes regardless of how small the numerical value of the exponentiation is.
6478
6479Since the function is given the entire RSA key (for private keys only) CRT is possible as prescribed in the PKCS \#1 v2.1 specification.
6480
6481\newpage
6482\markboth{Index}{Index}
6483\input{crypt.ind}
6484
6485\end{document}
6486
6487% $Source: /cvs/libtom/libtomcrypt/crypt.tex,v $
6488% $Revision: 1.123 $
6489% $Date: 2006/12/16 19:08:17 $
6490