Below is the file 'crypt.tex' from this revision. You can also download the file.
\documentclass[b5paper]{book} \usepackage{hyperref} \usepackage{makeidx} \usepackage{amssymb} \usepackage{color} \usepackage{alltt} \usepackage{graphicx} \usepackage{layout} \def\union{\cup} \def\intersect{\cap} \def\getsrandom{\stackrel{\rm R}{\gets}} \def\cross{\times} \def\cat{\hspace{0.5em} \| \hspace{0.5em}} \def\catn{$\|$} \def\divides{\hspace{0.3em} | \hspace{0.3em}} \def\nequiv{\not\equiv} \def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}} \def\lcm{{\rm lcm}} \def\gcd{{\rm gcd}} \def\log{{\rm log}} \def\ord{{\rm ord}} \def\abs{{\mathit abs}} \def\rep{{\mathit rep}} \def\mod{{\mathit\ mod\ }} \renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})} \newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor} \newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil} \def\Or{{\rm\ or\ }} \def\And{{\rm\ and\ }} \def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}} \def\implies{\Rightarrow} \def\undefined{{\rm ``undefined"}} \def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}} \let\oldphi\phi \def\phi{\varphi} \def\Pr{{\rm Pr}} \newcommand{\str}[1]{{\mathbf{#1}}} \def\F{{\mathbb F}} \def\N{{\mathbb N}} \def\Z{{\mathbb Z}} \def\R{{\mathbb R}} \def\C{{\mathbb C}} \def\Q{{\mathbb Q}} \def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}} \def\gap{\vspace{0.5ex}} \makeindex \begin{document} \title{A Tiny Crypto Library, \\ LibTomCrypt \\ Version 0.96} \author{Tom St Denis \\ \\ tomstdenis@iahu.ca \\ http://libtomcrypt.org \\ \\ Phone: 1-613-836-3160\\ 111 Banning Rd \\ Kanata, Ontario \\ K2L 1C3 \\ Canada } \maketitle This text and source code library are both hereby placed in the public domain. This book has been formatted for B5 [176x250] paper using the \LaTeX{} {\em book} macro package. \vspace{10cm} \begin{flushright}Open Source. Open Academia. Open Minds. \mbox{ } Tom St Denis, Ontario, Canada \end{flushright} \newpage \tableofcontents \chapter{Introduction} \section{What is the LibTomCrypt?} LibTomCrypt is a portable ANSI C cryptographic library that supports symmetric ciphers, one-way hashes, pseudo-random number generators, public key cryptography (via RSA,DH or ECC/DH) and a plethora of support routines. It is designed to compile out of the box with the GNU C Compiler (GCC) version 2.95.3 (and higher) and with MSVC version 6 in win32. The library has been successfully tested on quite a few other platforms ranging from the ARM7TDMI in a Gameboy Advanced to various PowerPC processors and even the MIPS processor in the PlayStation 2. Suffice it to say the code is portable. The library is designed so new ciphers/hashes/PRNGs can be added at runtime and the existing API (and helper API functions) will be able to use the new designs automatically. There exist self-check functions for each cipher and hash to ensure that they compile and execute to the published design specifications. The library also performs extensive parameter error checking and will give verbose error messages when possible. Essentially the library saves the time of having to implement the ciphers, hashes, prngs yourself. Typically implementing useful cryptography is an error prone business which means anything that can save considerable time and effort is a good thing. \subsection{What the library IS for?} The library typically serves as a basis for other protocols and message formats. For example, it should be possible to take the RSA routines out of this library, apply the appropriate message padding and get PKCS compliant RSA routines. Similarly SSL protocols could be formed on top of the low-level symmetric cipher functions. The goal of this package is to provide these low level core functions in a robust and easy to use fashion. The library also serves well as a toolkit for applications where they don't need to be OpenPGP, PKCS, etc. compliant. Included are fully operational public key routines for encryption, decryption, signature generation and verification. These routines are fully portable but are not conformant to any known set of standards\footnote{With the exception of the RSA code which is based on the PKCS \#1 standards.}. They are all based on established number theory and cryptography. \subsection{What the library IS NOT for?} The library is not designed to be in anyway an implementation of the SSL or OpenPGP standards. The library is not designed to be compliant with any known form of API or programming hierarchy. It is not a port of any other library and it is not platform specific (like the MS CSP). So if you're looking to drop in some buzzword compliant crypto library this is not for you. The library has been written from scratch to provide basic functions as well as non-standard higher level functions. This is not to say that the library is a ``homebrew'' project. All of the symmetric ciphers and one-way hash functions conform to published test vectors. The public key functions are derived from publicly available material and the majority of the code has been reviewed by a growing community of developers. \subsubsection{Why not?} You may be asking why I didn't choose to go all out and support standards like P1363, PKCS and the whole lot. The reason is quite simple too much money gets in the way. When I tried to access the P1363 draft documents and was denied (it requires a password) I realized that they're just a business anyways. See what happens is a company will sit down and invent a ``standard''. Then they try to sell it to as many people as they can. All of a sudden this ``standard'' is everywhere. Then the standard is updated every so often to keep people dependent. Then you become RSA. If people are supposed to support these standards they had better make them more accessible. \section{Why did I write it?} You may be wondering, ``Tom, why did you write a crypto library. I already have one.''. Well the reason falls into two categories: \begin{enumerate} \item I am too lazy to figure out someone else's API. I'd rather invent my own simpler API and use that. \item It was (still is) good coding practice. \end{enumerate} The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc. I'm trying to write my {\bf own} crypto library and hopefully along the way others will appreciate the work. With this library all core functions (ciphers, hashes, prngs) have the {\bf exact} same prototype definition. They all load and store data in a format independent of the platform. This means if you encrypt with Blowfish on a PPC it should decrypt on an x86 with zero problems. The consistent API also means that if you learn how to use blowfish with my library you know how to use Safer+ or RC6 or Serpent or ... as well. With all of the core functions there are central descriptor tables that can be used to make a program automatically pick between ciphers, hashes and PRNGs at runtime. That means your application can support all ciphers/hashes/prngs without changing the source code. \subsection{Modular} The LibTomCrypt package has also been written to be very modular. The block ciphers, one-way hashes and pseudo-random number generators (PRNG) are all used within the API through ``descriptor'' tables which are essentially structures with pointers to functions. While you can still call particular functions directly (\textit{e.g. sha256\_process()}) this descriptor interface allows the developer to customize their usage of the library. For example, consider a hardware platform with a specialized RNG device. Obviously one would like to tap that for the PRNG needs within the library (\textit{e.g. making a RSA key}). All the developer has todo is write a descriptor and the few support routines required for the device. After that the rest of the API can make use of it without change. Similiarly imagine a few years down the road when AES2 (\textit{or whatever they call it}) is invented. It can be added to the library and used within applications with zero modifications to the end applications provided they are written properly. This flexibility within the library means it can be used with any combination of primitive algorithms and unlike libraries like OpenSSL is not tied to direct routines. For instance, in OpenSSL there are CBC block mode routines for every single cipher. That means every time you add or remove a cipher from the library you have to update the associated support code as well. In LibTomCrypt the associated code (\textit{chaining modes in this case}) are not directly tied to the ciphers. That is a new cipher can be added to the library by simply providing the key setup, ECB decrypt and encrypt and test vector routines. After that all five chaining mode routines can make use of the cipher right away. \section{License} All of the source code except for the following files have been written by the author or donated to the project under a public domain license: \begin{enumerate} \item rc2.c \item safer.c \end{enumerate} `mpi.c'' was originally written by Michael Fromberger (sting@linguist.dartmouth.edu) but has since been replaced with my LibTomMath library. ``rc2.c'' is based on publicly available code that is not attributed to a person from the given source. ``safer.c'' was written by Richard De Moliner (demoliner@isi.ee.ethz.ch) and is public domain. The project is hereby released as public domain. \section{Patent Disclosure} The author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice. To the best of the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers. They can be removed from a build by simply commenting out the two appropriate lines in the makefile script. The rest of the ciphers and hashes are patent free or under patents that have since expired. The RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations. This means you can use the ciphers you just can't advertise that you are doing so. \section{Building the library} To build the library on a GCC equipped platform simply type ``make'' at your command prompt. It will build the library file ``libtomcrypt.a''. To install the library copy all of the ``.h'' files into your ``\#include'' path and the single libtomcrypt.a file into your library path. With MSVC you can build the library with ``nmake -f makefile.msvc''. This will produce a ``tomcrypt.lib'' file which is the core library. Copy the header files into your MSVC include path and the library in the lib path (typically under where VC98 is installed). \section{Building against the library} In the recent versions the build steps have changed. The build options are now stored in ``mycrypt\_custom.h'' and no longer in the makefile. If you change a build option in that file you must re-build the library from clean to ensure the build is intact. The perl script ``config.pl'' will help setup the custom header and a custom makefile if you want one (the provided ``makefile'' will work with custom configs). \section{Thanks} I would like to give thanks to the following people (in no particular order) for helping me develop this project: \begin{enumerate} \item Richard van de Laarschot \item Richard Heathfield \item Ajay K. Agrawal \item Brian Gladman \item Svante Seleborg \item Clay Culver \item Jason Klapste \item Dobes Vandermeer \item Daniel Richards \item Wayne Scott \item Andrew Tyler \item Sky Schulz \item Christopher Imes \end{enumerate} \chapter{The Application Programming Interface (API)} \section{Introduction} \index{CRYPT\_ERROR} \index{CRYPT\_OK} In general the API is very simple to memorize and use. Most of the functions return either {\bf void} or {\bf int}. Functions that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful or one of the many error codes if it failed. Certain functions that return int will return $-1$ to indicate an error. These functions will be explicitly commented upon. When a function does return a CRYPT error code it can be translated into a string with \index{error\_to\_string()} \begin{verbatim} const char *error_to_string(int err); \end{verbatim} An example of handling an error is: \begin{verbatim} void somefunc(void) { int err; /* call a cryptographic function */ if ((err = some_crypto_function(...)) != CRYPT_OK) { printf("A crypto error occured, %s\n", error_to_string(err)); /* perform error handling */ } /* continue on if no error occured */ } \end{verbatim} There is no initialization routine for the library and for the most part the code is thread safe. The only thread related issue is if you use the same symmetric cipher, hash or public key state data in multiple threads. Normally that is not an issue. To include the prototypes for ``LibTomCrypt.a'' into your own program simply include ``mycrypt.h'' like so: \begin{verbatim} #include <mycrypt.h> int main(void) { return 0; } \end{verbatim} The header file ``mycrypt.h'' also includes ``stdio.h'', ``string.h'', ``stdlib.h'', ``time.h'', ``ctype.h'' and ``mpi.h'' (the bignum library routines). \section{Macros} There are a few helper macros to make the coding process a bit easier. The first set are related to loading and storing 32/64-bit words in little/big endian format. The macros are: \index{STORE32L} \index{STORE64L} \index{LOAD32L} \index{LOAD64L} \index{STORE32H} \index{STORE64H} \index{LOAD32H} \index{LOAD64H} \index{BSWAP} \begin{small} \begin{center} \begin{tabular}{|c|c|c|} \hline STORE32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 3]$ \\ \hline STORE64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 7]$ \\ \hline LOAD32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[0 \ldots 3] \to x$ \\ \hline LOAD64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[0 \ldots 7] \to x$ \\ \hline STORE32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[3 \ldots 0]$ \\ \hline STORE64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[7 \ldots 0]$ \\ \hline LOAD32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[3 \ldots 0] \to x$ \\ \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\ \hline BSWAP(x) & {\bf unsigned long} x & Swaps the byte order of x. \\ \hline \end{tabular} \end{center} \end{small} There are 32-bit cyclic rotations as well: \index{ROL} \index{ROR} \begin{center} \begin{tabular}{|c|c|c|} \hline ROL(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y$ \\ \hline ROR(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y$ \\ \hline \end{tabular} \end{center} \section{Functions with Variable Length Output} Certain functions such as (for example) ``rsa\_export()'' give an output that is variable length. To prevent buffer overflows you must pass it the length of the buffer\footnote{Extensive error checking is not in place but it will be in future releases so it is a good idea to follow through with these guidelines.} where the output will be stored. For example: \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { rsa_key key; unsigned char buffer[1024]; unsigned long x; int err; /* ... Make up the RSA key somehow */ /* lets export the key, set x to the size of the output buffer */ x = sizeof(buffer); if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) { printf("Export error: %s\n", error_to_string(err)); return -1; } /* if rsa_export() was successful then x will have the size of the output */ printf("RSA exported key takes %d bytes\n", x); /* ... do something with the buffer */ return 0; } \end{verbatim} \end{small} In the above example if the size of the RSA public key was more than 1024 bytes this function would not store anything in either ``buffer'' or ``x'' and simply return an error code. If the function suceeds it stores the length of the output back into ``x'' so that the calling application will know how many bytes used. \section{Functions that need a PRNG} Certain functions such as ``rsa\_make\_key()'' require a PRNG. These functions do not setup the PRNG themselves so it is the responsibility of the calling function to initialize the PRNG before calling them. \section{Functions that use Arrays of Octets} Most functions require inputs that are arrays of the data type ``unsigned char''. Whether it is a symmetric key, IV for a chaining mode or public key packet it is assumed that regardless of the actual size of ``unsigned char'' only the lower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine you must pass it in (a pointer to) an array of 32 ``unsigned char'' variables. Certain routines (such as SAFER+) take special care to work properly on platforms where an ``unsigned char'' is not eight bits. For the purposes of this library the term ``byte'' will refer to an octet or eight bit word. Typically an array of type ``byte'' will be synonymous with an array of type ``unsigned char''. \chapter{Symmetric Block Ciphers} \section{Core Functions} Libtomcrypt provides several block ciphers all in a plain vanilla ECB block mode. Its important to first note that you should never use the ECB modes directly to encrypt data. Instead you should use the ECB functions to make a chaining mode or use one of the provided chaining modes. All of the ciphers are written as ECB interfaces since it allows the rest of the API to grow in a modular fashion. All ciphers store their scheduled keys in a single data type called ``symmetric\_key''. This allows all ciphers to have the same prototype and store their keys as naturally as possible. All ciphers provide five visible functions which are (given that XXX is the name of the cipher): \index{Cipher Setup} \begin{verbatim} int XXX_setup(const unsigned char *key, int keylen, int rounds, symmetric_key *skey); \end{verbatim} The XXX\_setup() routine will setup the cipher to be used with a given number of rounds and a given key length (in bytes). The number of rounds can be set to zero to use the default, which is generally a good idea. If the function returns successfully the variable ``skey'' will have a scheduled key stored in it. Its important to note that you should only used this scheduled key with the intended cipher. For example, if you call ``blowfish\_setup()'' do not pass the scheduled key onto ``rc5\_ecb\_encrypt()''. All setup functions do not allocate memory off the heap so when you are done with a key you can simply discard it (e.g. they can be on the stack). To encrypt or decrypt a block in ECB mode there are these two functions: \index{Cipher Encrypt} \index{Cipher Decrypt} \begin{verbatim} void XXX_ecb_encrypt(const unsigned char *pt, unsigned char *ct, symmetric_key *skey); void XXX_ecb_decrypt(const unsigned char *ct, unsigned char *pt, symmetric_key *skey); \end{verbatim} These two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on which cipher you are using.} and store the result where you want it. It is possible that the input and output buffer are the same buffer. For the encrypt function ``pt''\footnote{pt stands for plaintext.} is the input and ``ct'' is the output. For the decryption function its the opposite. To test a particular cipher against test vectors\footnote{As published in their design papers.} call: \index{Cipher Testing} \begin{verbatim} int XXX_test(void); \end{verbatim} This function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is based upon. Finally for each cipher there is a function which will help find a desired key size: \begin{verbatim} int XXX_keysize(int *keysize); \end{verbatim} Essentially it will round the input keysize in ``keysize'' down to the next appropriate key size. This function return {\bf CRYPT\_OK} if the key size specified is acceptable. For example: \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { int keysize, err; /* now given a 20 byte key what keysize does Twofish want to use? */ keysize = 20; if ((err = twofish_keysize(&keysize)) != CRYPT_OK) { printf("Error getting key size: %s\n", error_to_string(err)); return -1; } printf("Twofish suggested a key size of %d\n", keysize); return 0; } \end{verbatim} \end{small} This should indicate a keysize of sixteen bytes is suggested. An example snippet that encodes a block with Blowfish in ECB mode is below. \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { unsigned char pt[8], ct[8], key[8]; symmetric_key skey; int err; /* ... key is loaded appropriately in ``key'' ... */ /* ... load a block of plaintext in ``pt'' ... */ /* schedule the key */ if ((err = blowfish_setup(key, /* the key we will use */ 8, /* key is 8 bytes (64-bits) long */ 0, /* 0 == use default # of rounds */ &skey) /* where to put the scheduled key */ ) != CRYPT_OK) { printf("Setup error: %s\n", error_to_string(err)); return -1; } /* encrypt the block */ blowfish_ecb_encrypt(pt, /* encrypt this 8-byte array */ ct, /* store encrypted data here */ &skey); /* our previously scheduled key */ /* decrypt the block */ blowfish_ecb_decrypt(ct, /* decrypt this 8-byte array */ pt, /* store decrypted data here */ &skey); /* our previously scheduled key */ return 0; } \end{verbatim} \end{small} \section{Key Sizes and Number of Rounds} \index{Symmetric Keys} As a general rule of thumb do not use symmetric keys under 80 bits if you can. Only a few of the ciphers support smaller keys (mainly for test vectors anyways). Ideally your application should be making at least 256 bit keys. This is not because you're supposed to be paranoid. Its because if your PRNG has a bias of any sort the more bits the better. For example, if you have $\mbox{Pr}\left[X = 1\right] = {1 \over 2} \pm \gamma$ where $\vert \gamma \vert > 0$ then the total amount of entropy in N bits is $N \cdot -log_2\left ({1 \over 2} + \vert \gamma \vert \right)$. So if $\gamma$ were $0.25$ (a severe bias) a 256-bit string would have about 106 bits of entropy whereas a 128-bit string would have only 53 bits of entropy. The number of rounds of most ciphers is not an option you can change. Only RC5 allows you to change the number of rounds. By passing zero as the number of rounds all ciphers will use their default number of rounds. Generally the ciphers are configured such that the default number of rounds provide adequate security for the given block size. \section{The Cipher Descriptors} \index{Cipher Descriptor} To facilitate automatic routines an array of cipher descriptors is provided in the array ``cipher\_descriptor''. An element of this array has the following format: \begin{verbatim} struct _cipher_descriptor { char *name; unsigned long min_key_length, max_key_length, block_length, default_rounds; int (*setup) (const unsigned char *key, int keylength, int num_rounds, symmetric_key *skey); void (*ecb_encrypt)(const unsigned char *pt, unsigned char *ct, symmetric_key *key); void (*ecb_decrypt)(const unsigned char *ct, unsigned char *pt, symmetric_key *key); int (*test) (void); int (*keysize) (int *desired_keysize); }; \end{verbatim} Where ``name'' is the lower case ASCII version of the name. The fields ``min\_key\_length'', ``max\_key\_length'' and ``block\_length'' are all the number of bytes not bits. As a good rule of thumb it is assumed that the cipher supports the min and max key lengths but not always everything in between. The ``default\_rounds'' field is the default number of rounds that will be used. The remaining fields are all pointers to the core functions for each cipher. The end of the cipher\_descriptor array is marked when ``name'' equals {\bf NULL}. As of this release the current cipher\_descriptors elements are \index{Cipher descriptor table} \begin{small} \begin{center} \begin{tabular}{|c|c|c|c|c|c|} \hline Name & Descriptor Name & Block Size & Key Range & Rounds \\ \hline Blowfish & blowfish\_desc & 8 & 8 $\ldots$ 56 & 16 \\ \hline X-Tea & xtea\_desc & 8 & 16 & 32 \\ \hline RC2 & rc2\_desc & 8 & 8 $\ldots$ 128 & 16 \\ \hline RC5-32/12/b & rc5\_desc & 8 & 8 $\ldots$ 128 & 12 $\ldots$ 24 \\ \hline RC6-32/20/b & rc6\_desc & 16 & 8 $\ldots$ 128 & 20 \\ \hline SAFER+ & saferp\_desc &16 & 16, 24, 32 & 8, 12, 16 \\ \hline Safer K64 & safer\_k64\_desc & 8 & 8 & 6 $\ldots$ 13 \\ \hline Safer SK64 & safer\_sk64\_desc & 8 & 8 & 6 $\ldots$ 13 \\ \hline Safer K128 & safer\_k128\_desc & 8 & 16 & 6 $\ldots$ 13 \\ \hline Safer SK128 & safer\_sk128\_desc & 8 & 16 & 6 $\ldots$ 13 \\ \hline AES & aes\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\ & aes\_enc\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\ \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\ \hline DES & des\_desc & 8 & 7 & 16 \\ \hline 3DES (EDE mode) & des3\_desc & 8 & 21 & 16 \\ \hline CAST5 (CAST-128) & cast5\_desc & 8 & 5 $\ldots$ 16 & 12, 16 \\ \hline Noekeon & noekeon\_desc & 16 & 16 & 16 \\ \hline Skipjack & skipjack\_desc & 8 & 10 & 32 \\ \hline \end{tabular} \end{center} \end{small} \subsection{Notes} \begin{small} \begin{enumerate} \item For AES (also known as Rijndael) there are four descriptors which complicate issues a little. The descriptors rijndael\_desc and rijndael\_enc\_desc provide the cipher named ``rijndael''. The descriptors aes\_desc and aes\_enc\_desc provide the cipher name ``aes''. Functionally both ``rijndael'' and ``aes'' are the same cipher. The only difference is when you call find\_cipher() you have to pass the correct name. The cipher descriptors with ``enc'' in the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine and tables. The decryption and self--test function pointers of both ``encrypt only'' descriptors are set to \textbf{NULL} and should not be called. The ``encrypt only'' descriptors are useful for applications that only use the encryption function of the cipher. Algorithms such as EAX, PMAC and OMAC only require the encryption function. So far this ``encrypt only'' functionality has only been implemented for Rijndael as it makes the most sense for this cipher. \item For the 64-bit SAFER famliy of ciphers (e.g K64, SK64, K128, SK128) the ecb\_encrypt() and ecb\_decrypt() functions are the same. So if you want to use those functions directly just call safer\_ecb\_encrypt() or safer\_ecb\_decrypt() respectively. \item Note that for ``DES'' and ``3DES'' they use 8 and 24 byte keys but only 7 and 21 [respectively] bytes of the keys are in fact used for the purposes of encryption. My suggestion is just to use random 8/24 byte keys instead of trying to make a 8/24 byte string from the real 7/21 byte key. \item Note that ``Twofish'' has additional configuration options that take place at build time. These options are found in the file ``mycrypt\_cfg.h''. The first option is ``TWOFISH\_SMALL'' which when defined will force the Twofish code to not pre-compute the Twofish ``$g(X)$'' function as a set of four $8 \times 32$ s-boxes. This means that a scheduled key will require less ram but the resulting cipher will be slower. The second option is ``TWOFISH\_TABLES'' which when defined will force the Twofish code to use pre-computed tables for the two s-boxes $q_0, q_1$ as well as the multiplication by the polynomials 5B and EF used in the MDS multiplication. As a result the code is faster and slightly larger. The speed increase is useful when ``TWOFISH\_SMALL'' is defined since the s-boxes and MDS multiply form the heart of the Twofish round function. \index{Twofish build options} \begin{small} \begin{center} \begin{tabular}{|l|l|l|} \hline TWOFISH\_SMALL & TWOFISH\_TABLES & Speed and Memory (per key) \\ \hline undefined & undefined & Very fast, 4.2KB of ram. \\ \hline undefined & defined & As above, faster keysetup, larger code (1KB more). \\ \hline defined & undefined & Very slow, 0.2KB of ram. \\ \hline defined & defined & Somewhat faster, 0.2KB of ram, larger code. \\ \hline \end{tabular} \end{center} \end{small} \end{enumerate} \end{small} To work with the cipher\_descriptor array there is a function: \index{find\_cipher()} \begin{verbatim} int find_cipher(char *name) \end{verbatim} Which will search for a given name in the array. It returns negative one if the cipher is not found, otherwise it returns the location in the array where the cipher was found. For example, to indirectly setup Blowfish you can also use: \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { unsigned char key[8]; symmetric_key skey; int err; /* you must register a cipher before you use it */ if (register_cipher(&blowfish_desc)) == -1) { printf("Unable to register Blowfish cipher."); return -1; } /* generic call to function (assuming the key in key[] was already setup) */ if ((err = cipher_descriptor[find_cipher("blowfish")].setup(key, 8, 0, &skey)) != CRYPT_OK) { printf("Error setting up Blowfish: %s\n", error_to_string(err)); return -1; } /* ... use cipher ... */ } \end{verbatim} \end{small} A good safety would be to check the return value of ``find\_cipher()'' before accessing the desired function. In order to use a cipher with the descriptor table you must register it first using: \index{register\_cipher()} \begin{verbatim} int register_cipher(const struct _cipher_descriptor *cipher); \end{verbatim} Which accepts a pointer to a descriptor and returns the index into the global descriptor table. If an error occurs such as there is no more room (it can have 32 ciphers at most) it will return {\bf{-1}}. If you try to add the same cipher more than once it will just return the index of the first copy. To remove a cipher call: \index{unregister\_cipher()} \begin{verbatim} int unregister_cipher(const struct _cipher_descriptor *cipher); \end{verbatim} Which returns {\bf CRYPT\_OK} if it removes it otherwise it returns {\bf CRYPT\_ERROR}. Consider: \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { int err; /* register the cipher */ if (register_cipher(&rijndael_desc) == -1) { printf("Error registering Rijndael\n"); return -1; } /* use Rijndael */ /* remove it */ if ((err = unregister_cipher(&rijndael_desc)) != CRYPT_OK) { printf("Error removing Rijndael: %s\n", error_to_string(err)); return -1; } return 0; } \end{verbatim} \end{small} This snippet is a small program that registers only Rijndael only. \section{Symmetric Modes of Operations} \subsection{Background} A typical symmetric block cipher can be used in chaining modes to effectively encrypt messages larger than the block size of the cipher. Given a key $k$, a plaintext $P$ and a cipher $E$ we shall denote the encryption of the block $P$ under the key $k$ as $E_k(P)$. In some modes there exists an initial vector denoted as $C_{-1}$. \subsubsection{ECB Mode} \index{ECB mode} ECB or Electronic Codebook Mode is the simplest method to use. It is given as: \begin{equation} C_i = E_k(P_i) \end{equation} This mode is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more than once. \subsubsection{CBC Mode} \index{CBC mode} CBC or Cipher Block Chaining mode is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers. It is given as: \begin{equation} C_i = E_k(P_i \oplus C_{i - 1}) \end{equation} It is important that the initial vector be unique and preferably random for each message encrypted under the same key. \subsubsection{CTR Mode} \index{CTR mode} CTR or Counter Mode is a mode which only uses the encryption function of the cipher. Given a initial vector which is treated as a large binary counter the CTR mode is given as: \begin{eqnarray} C_{-1} = C_{-1} + 1\mbox{ }(\mbox{mod }2^W) \nonumber \\ C_i = P_i \oplus E_k(C_{-1}) \end{eqnarray} Where $W$ is the size of a block in bits (e.g. 64 for Blowfish). As long as the initial vector is random for each message encrypted under the same key replay and swap attacks are infeasible. CTR mode may look simple but it is as secure as the block cipher is under a chosen plaintext attack (provided the initial vector is unique). \subsubsection{CFB Mode} \index{CFB mode} CFB or Ciphertext Feedback Mode is a mode akin to CBC. It is given as: \begin{eqnarray} C_i = P_i \oplus C_{-1} \nonumber \\ C_{-1} = E_k(C_i) \end{eqnarray} Note that in this library the output feedback width is equal to the size of the block cipher. That is this mode is used to encrypt whole blocks at a time. However, the library will buffer data allowing the user to encrypt or decrypt partial blocks without a delay. When this mode is first setup it will initially encrypt the initial vector as required. \subsubsection{OFB Mode} \index{OFB mode} OFB or Output Feedback Mode is a mode akin to CBC as well. It is given as: \begin{eqnarray} C_{-1} = E_k(C_{-1}) \nonumber \\ C_i = P_i \oplus C_{-1} \end{eqnarray} Like the CFB mode the output width in CFB mode is the same as the width of the block cipher. OFB mode will also buffer the output which will allow you to encrypt or decrypt partial blocks without delay. \subsection{Choice of Mode} My personal preference is for the CTR mode since it has several key benefits: \begin{enumerate} \item No short cycles which is possible in the OFB and CFB modes. \item Provably as secure as the block cipher being used under a chosen plaintext attack. \item Technically does not require the decryption routine of the cipher. \item Allows random access to the plaintext. \item Allows the encryption of block sizes that are not equal to the size of the block cipher. \end{enumerate} The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size. They accomplish this by buffering the data required to complete a block. This allows you to encrypt or decrypt any size block of memory with either of the three modes. The ECB and CBC modes process blocks of the same size as the cipher at a time. Therefore they are less flexible than the other modes. \subsection{Implementation} \index{CBC Mode} \index{CTR Mode} \index{OFB Mode} \index{CFB Mode} The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode you want is XXX there is a structure called ``symmetric\_XXX'' that will contain the information required to use that mode. They have identical setup routines (except ECB mode for obvious reasons): \index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()} \begin{verbatim} int XXX_start(int cipher, const unsigned char *IV, const unsigned char *key, int keylen, int num_rounds, symmetric_XXX *XXX); int ecb_start(int cipher, const unsigned char *key, int keylen, int num_rounds, symmetric_ECB *ecb); \end{verbatim} In each case ``cipher'' is the index into the cipher\_descriptor array of the cipher you want to use. The ``IV'' value is the initialization vector to be used with the cipher. You must fill the IV yourself and it is assumed they are the same length as the block size\footnote{In otherwords the size of a block of plaintext for the cipher, e.g. 8 for DES, 16 for AES, etc.} of the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The parameters ``key'', ``keylen'' and ``num\_rounds'' are the same as in the XXX\_setup() function call. The final parameter is a pointer to the structure you want to hold the information for the mode of operation. Both routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise they return an error code. To actually encrypt or decrypt the following routines are provided: \index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()} \index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()} \begin{verbatim} int XXX_encrypt(const unsigned char *pt, unsigned char *ct, symmetric_XXX *XXX); int XXX_decrypt(const unsigned char *ct, unsigned char *pt, symmetric_XXX *XXX); int YYY_encrypt(const unsigned char *pt, unsigned char *ct, unsigned long len, symmetric_YYY *YYY); int YYY_decrypt(const unsigned char *ct, unsigned char *pt, unsigned long len, symmetric_YYY *YYY); \end{verbatim} Where ``XXX'' is one of (ecb, cbc) and ``YYY'' is one of (ctr, ofb, cfb). In the CTR, OFB and CFB cases ``len'' is the size of the buffer (as number of chars) to encrypt or decrypt. The CTR, OFB and CFB modes are order sensitive but not chunk sensitive. That is you can encrypt ``ABCDEF'' in three calls like ``AB'', ``CD'', ``EF'' or two like ``ABCDE'' and ``F'' and end up with the same ciphertext. However, encrypting ``ABC'' and ``DABC'' will result in different ciphertexts. All five of the modes will return {\bf CRYPT\_OK} on success from the encrypt or decrypt functions. To decrypt in either mode you simply perform the setup like before (recall you have to fetch the IV value you used) and use the decrypt routine on all of the blocks. To change or read the IV of a previously initialized chaining mode use the following two functions. \index{cbc\_setiv()} \index{cbc\_getiv()} \index{ofb\_setiv()} \index{ofb\_getiv()} \index{cfb\_setiv()} \index{cfb\_getiv()} \index{ctr\_setiv()} \index{ctr\_getiv()} \begin{verbatim} int XXX_getiv(unsigned char *IV, unsigned long *len, symmetric_XXX *XXX); int XXX_setiv(const unsigned char *IV, unsigned long len, symmetric_XXX *XXX); \end{verbatim} The XXX\_getiv function will read the IV out of the chaining mode and store it into ``IV'' along with the length of the IV stored in ``len''. The XXX\_setiv will initialize the chaining mode state as if the original IV were the new IV specified. The length of the IV passed in must be the size of the ciphers block size. The XXX\_setiv functions are handy if you wish to change the IV without re--keying the cipher. \newpage \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { unsigned char key[16], IV[16], buffer[512]; symmetric_CTR ctr; int x, err; /* register twofish first */ if (register_cipher(&twofish_desc) == -1) { printf("Error registering cipher.\n"); return -1; } /* somehow fill out key and IV */ /* start up CTR mode */ if ((err = ctr_start(find_cipher("twofish"), /* index of desired cipher */ IV, /* the initial vector */ key, /* the secret key */ 16, /* length of secret key (16 bytes, 128 bits) */ 0, /* 0 == default # of rounds */ &ctr) /* where to store initialized CTR state */ ) != CRYPT_OK) { printf("ctr_start error: %s\n", error_to_string(err)); return -1; } /* somehow fill buffer than encrypt it */ if ((err = ctr_encrypt( buffer, /* plaintext */ buffer, /* ciphertext */ sizeof(buffer), /* length of data to encrypt */ &ctr) /* previously initialized CTR state */ ) != CRYPT_OK) { printf("ctr_encrypt error: %s\n", error_to_string(err)); return -1; } /* make use of ciphertext... */ /* now we want to decrypt so let's use ctr_setiv */ if ((err = ctr_setiv( IV, /* the initial IV we gave to ctr_start */ 16, /* the IV is 16 bytes long */ &ctr) /* the ctr state we wish to modify */ ) != CRYPT_OK) { printf("ctr_setiv error: %s\n", error_to_string(err)); return -1; } if ((err = ctr_decrypt( buffer, /* ciphertext */ buffer, /* plaintext */ sizeof(buffer), /* length of data to encrypt */ &ctr) /* previously initialized CTR state */ ) != CRYPT_OK) { printf("ctr_decrypt error: %s\n", error_to_string(err)); return -1; } /* clear up and return */ zeromem(key, sizeof(key)); zeromem(&ctr, sizeof(ctr)); return 0; } \end{verbatim} \end{small} \section{Encrypt and Authenticate Modes} \subsection{EAX Mode} LibTomCrypt provides support for a mode called EAX\footnote{See M. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the way it was intended to be used by the designers. First a short description of what EAX mode is before I explain how to use it. EAX is a mode that requires a cipher, CTR and OMAC support and provides encryption and authentication\footnote{Note that since EAX only requires OMAC and CTR you may use ``encrypt only'' cipher descriptors with this mode.}. It is initialized with a random ``nonce'' that can be shared publicly as well as a ``header'' which can be fixed and public as well as a random secret symmetric key. The ``header'' data is meant to be meta-data associated with a stream that isn't private (e.g. protocol messages). It can be added at anytime during an EAX stream and is part of the authentication tag. That is, changes in the meta-data can be detected by changes in the output tag. The mode can then process plaintext producing ciphertext as well as compute a partial checksum. The actual checksum called a ``tag'' is only emitted when the message is finished. In the interim though the user can process any arbitrary sized message block to send to the recipient as ciphertext. This makes the EAX mode especially suited for streaming modes of operation. The mode is initialized with the following function. \index{eax\_init()} \begin{verbatim} int eax_init(eax_state *eax, int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *nonce, unsigned long noncelen, const unsigned char *header, unsigned long headerlen); \end{verbatim} Where ``eax'' is the EAX state. ``cipher'' is the index of the desired cipher in the descriptor table. ``key'' is the shared secret symmetric key of length ``keylen''. ``nonce'' is the random public string of length ``noncelen''. ``header'' is the random (or fixed or \textbf{NULL}) header for the message of length ``headerlen''. When this function completes ``eax'' will be initialized such that you can now either have data decrypted or encrypted in EAX mode. Note that if ``headerlen'' is zero you may pass ``header'' as \textbf{NULL} to indicate there is no initial header data. To encrypt or decrypt data in a streaming mode use the following. \index{eax\_encrypt()} \index{eax\_decrypt()} \begin{verbatim} int eax_encrypt(eax_state *eax, const unsigned char *pt, unsigned char *ct, unsigned long length); int eax_decrypt(eax_state *eax, const unsigned char *ct, unsigned char *pt, unsigned long length); \end{verbatim} The function ``eax\_encrypt'' will encrypt the bytes in ``pt'' of ``length'' bytes and store the ciphertext in ``ct''. Note that ``ct'' and ``pt'' may be the same region in memory. This function will also send the ciphertext through the OMAC function. The function ``eax\_decrypt'' decrypts ``ct'' and stores it in ``pt''. This also allows ``pt'' and ``ct'' to be the same region in memory. You cannot both encrypt or decrypt with the same ``eax'' context. For bi-directional communication you will need to initialize two EAX contexts (preferably with different headers and nonces). Note that both of these functions allow you to send the data in any granularity but the order is important. While the eax\_init() function allows you to add initial header data to the stream you can also add header data during the EAX stream with the following. \index{eax\_addheader()} \begin{verbatim} int eax_addheader(eax_state *eax, const unsigned char *header, unsigned long length); \end{verbatim} This will add the ``length'' bytes from ``header'' to the given ``eax'' stream. Once the message is finished the ``tag'' (checksum) may be computed with the following function. \index{eax\_done()} \begin{verbatim} int eax_done(eax_state *eax, unsigned char *tag, unsigned long *taglen); \end{verbatim} This will terminate the EAX state ``eax'' and store upto ``taglen'' bytes of the message tag in ``tag''. The function then stores how many bytes of the tag were written out back into ``taglen''. The EAX mode code can be tested to ensure it matches the test vectors by calling the following function. \index{eax\_test()} \begin{verbatim} int eax_test(void); \end{verbatim} This requires that the AES (or Rijndael) block cipher be registered with the cipher\_descriptor table first. \begin{verbatim} #include <mycrypt.h> int main(void) { int err; eax_state eax; unsigned char pt[64], ct[64], nonce[16], key[16], tag[16]; unsigned long taglen; if (register_cipher(&rijndael_desc) == -1) { printf("Error registering Rijndael"); return EXIT_FAILURE; } /* ... make up random nonce and key ... */ /* initialize context */ if ((err = eax_init( &eax, /* the context */ find_cipher("rijndael"), /* cipher we want to use */ nonce, /* our state nonce */ 16, /* none is 16 bytes */ "TestApp", /* example header, identifies this program */ 7) /* length of the header */ ) != CRYPT_OK) { printf("Error eax_init: %s", error_to_string(err)); return EXIT_FAILURE; } /* now encrypt data, say in a loop or whatever */ if ((err = eax_encrypt( &eax, /* eax context */ pt, /* plaintext (source) */ ct, /* ciphertext (destination) */ sizeof(pt) /* size of plaintext */ ) != CRYPT_OK) { printf("Error eax_encrypt: %s", error_to_string(err)); return EXIT_FAILURE; } /* finish message and get authentication tag */ taglen = sizeof(tag); if ((err = eax_done( &eax, /* eax context */ tag, /* where to put tag */ &taglen /* length of tag space */ ) != CRYPT_OK) { printf("Error eax_done: %s", error_to_string(err)); return EXIT_FAILURE; } /* now we have the authentication tag in "tag" and it's taglen bytes long */ } \end{verbatim} You can also perform an entire EAX state on a block of memory in a single function call with the following functions. \index{eax\_encrypt\_authenticate\_memory} \index{eax\_decrypt\_verify\_memory} \begin{verbatim} int eax_encrypt_authenticate_memory(int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *nonce, unsigned long noncelen, const unsigned char *header, unsigned long headerlen, const unsigned char *pt, unsigned long ptlen, unsigned char *ct, unsigned char *tag, unsigned long *taglen); int eax_decrypt_verify_memory(int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *nonce, unsigned long noncelen, const unsigned char *header, unsigned long headerlen, const unsigned char *ct, unsigned long ctlen, unsigned char *pt, unsigned char *tag, unsigned long taglen, int *res); \end{verbatim} Both essentially just call eax\_init() followed by eax\_encrypt() (or eax\_decrypt() respectively) and eax\_done(). The parameters have the same meaning as with those respective functions. The 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 the tag it computed while decrypting the message. If the tags match then it stores a $1$ in ``res'', otherwise it stores a $0$. \subsection{OCB Mode} LibTomCrypt provides support for a mode called OCB\footnote{See P. Rogaway, M. Bellare, J. Black, T. Krovetz, ``OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption''.} . OCB is an encryption protocol that simultaneously provides authentication. It is slightly faster to use than EAX mode but is less flexible. Let's review how to initialize an OCB context. \index{ocb\_init()} \begin{verbatim} int ocb_init(ocb_state *ocb, int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *nonce); \end{verbatim} This will initialize the ``ocb'' context using cipher descriptor ``cipher''. It will use a ``key'' of length ``keylen'' and the random ``nonce''. Note that ``nonce'' must be a random (public) string the same length as the block ciphers block size (e.g. 16 bytes for AES). This mode has no ``Associated Data'' like EAX mode does which means you cannot authenticate metadata along with the stream. To encrypt or decrypt data use the following. \index{ocb\_encrypt()} \index{ocb\_decrypt()} \begin{verbatim} int ocb_encrypt(ocb_state *ocb, const unsigned char *pt, unsigned char *ct); int ocb_decrypt(ocb_state *ocb, const unsigned char *ct, unsigned char *pt); \end{verbatim} This will encrypt (or decrypt for the latter) a fixed length of data from ``pt'' to ``ct'' (vice versa for the latter). They assume that ``pt'' and ``ct'' are the same size as the block cipher's block size. Note that you cannot call both functions given a single ``ocb'' state. For bi-directional communication you will have to initialize two ``ocb'' states (with different nonces). Also ``pt'' and ``ct'' may point to the same location in memory. When you are finished encrypting the message you call the following function to compute the tag. \index{ocb\_done\_encrypt()} \begin{verbatim} int ocb_done_encrypt(ocb_state *ocb, const unsigned char *pt, unsigned long ptlen, unsigned char *ct, unsigned char *tag, unsigned long *taglen); \end{verbatim} This will terminate an encrypt stream ``ocb''. If you have trailing bytes of plaintext that will not complete a block you can pass them here. This will also encrypt the ``ptlen'' bytes in ``pt'' and store them in ``ct''. It will also store upto ``taglen'' bytes of the tag into ``tag''. Note that ``ptlen'' must be less than or equal to the block size of block cipher chosen. Also note that if you have an input message equal to the length of the block size then you pass the data here (not to ocb\_encrypt()) only. To terminate a decrypt stream and compared the tag you call the following. \index{ocb\_done\_decrypt()} \begin{verbatim} int ocb_done_decrypt(ocb_state *ocb, const unsigned char *ct, unsigned long ctlen, unsigned char *pt, const unsigned char *tag, unsigned long taglen, int *res); \end{verbatim} Similarly to the previous function you can pass trailing message bytes into this function. This will compute the tag of the message (internally) and then compare it against the ``taglen'' bytes of ``tag'' provided. By default ``res'' is set to zero. If all ``taglen'' bytes of ``tag'' can be verified then ``res'' is set to one (authenticated message). To make life simpler the following two functions are provided for memory bound OCB. \index{ocb\_encrypt\_authenticate\_memory()} \begin{verbatim} int ocb_encrypt_authenticate_memory(int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *nonce, const unsigned char *pt, unsigned long ptlen, unsigned char *ct, unsigned char *tag, unsigned long *taglen); \end{verbatim} This will OCB encrypt the message ``pt'' of length ``ptlen'' and store the ciphertext in ``ct''. The length ``ptlen'' can be any arbitrary length. \index{ocb\_decrypt\_verify\_memory()} \begin{verbatim} int ocb_decrypt_verify_memory(int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *nonce, const unsigned char *ct, unsigned long ctlen, unsigned char *pt, const unsigned char *tag, unsigned long taglen, int *res); \end{verbatim} Similarly this will OCB decrypt and compare the internally computed tag against the tag provided. ``res'' is set appropriately. \chapter{One-Way Cryptographic Hash Functions} \section{Core Functions} Like the ciphers there are hash core functions and a universal data type to hold the hash state called ``hash\_state''. To initialize hash XXX (where XXX is the name) call: \index{Hash Functions} \begin{verbatim} void XXX_init(hash_state *md); \end{verbatim} This simply sets up the hash to the default state governed by the specifications of the hash. To add data to the message being hashed call: \begin{verbatim} int XXX_process(hash_state *md, const unsigned char *in, unsigned long len); \end{verbatim} Essentially all hash messages are virtually infinitely\footnote{Most hashes are limited to $2^{64}$ bits or 2,305,843,009,213,693,952 bytes.} long message which are buffered. The data can be passed in any sized chunks as long as the order of the bytes are the same the message digest (hash output) will be the same. For example, this means that: \begin{verbatim} md5_process(&md, "hello ", 6); md5_process(&md, "world", 5); \end{verbatim} Will produce the same message digest as the single call: \index{Message Digest} \begin{verbatim} md5_process(&md, "hello world", 11); \end{verbatim} To finally get the message digest (the hash) call: \begin{verbatim} int XXX_done(hash_state *md, unsigned char *out); \end{verbatim} This function will finish up the hash and store the result in the ``out'' array. You must ensure that ``out'' is long enough for the hash in question. Often hashes are used to get keys for symmetric ciphers so the ``XXX\_done()'' functions will wipe the ``md'' variable before returning automatically. To test a hash function call: \begin{verbatim} int XXX_test(void); \end{verbatim} This will return {\bf CRYPTO\_OK} if the hash matches the test vectors, otherwise it returns an error code. An example snippet that hashes a message with md5 is given below. \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { hash_state md; unsigned char *in = "hello world", out[16]; /* setup the hash */ md5_init(&md); /* add the message */ md5_process(&md, in, strlen(in)); /* get the hash in out[0..15] */ md5_done(&md, out); return 0; } \end{verbatim} \end{small} \section{Hash Descriptors} Like the set of ciphers the set of hashes have descriptors too. They are stored in an array called ``hash\_descriptor'' and are defined by: \begin{verbatim} struct _hash_descriptor { char *name; unsigned long hashsize; /* digest output size in bytes */ unsigned long blocksize; /* the block size the hash uses */ void (*init) (hash_state *); int (*process)(hash_state *, const unsigned char *, unsigned long); int (*done) (hash_state *, unsigned char *); int (*test) (void); }; \end{verbatim} Similarly ``name'' is the name of the hash function in ASCII (all lowercase). ``hashsize'' is the size of the digest output in bytes. The remaining fields are pointers to the functions that do the respective tasks. There is a function to search the array as well called ``int find\_hash(char *name)''. It returns -1 if the hash is not found, otherwise the position in the descriptor table of the hash. You can use the table to indirectly call a hash function that is chosen at runtime. For example: \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { unsigned char buffer[100], hash[MAXBLOCKSIZE]; int idx, x; hash_state md; /* register hashes .... */ if (register_hash(&md5_desc) == -1) { printf("Error registering MD5.\n"); return -1; } /* register other hashes ... */ /* prompt for name and strip newline */ printf("Enter hash name: \n"); fgets(buffer, sizeof(buffer), stdin); buffer[strlen(buffer) - 1] = 0; /* get hash index */ idx = find_hash(buffer); if (idx == -1) { printf("Invalid hash name!\n"); return -1; } /* hash input until blank line */ hash_descriptor[idx].init(&md); while (fgets(buffer, sizeof(buffer), stdin) != NULL) hash_descriptor[idx].process(&md, buffer, strlen(buffer)); hash_descriptor[idx].done(&md, hash); /* dump to screen */ for (x = 0; x < hash_descriptor[idx].hashsize; x++) printf("%02x ", hash[x]); printf("\n"); return 0; } \end{verbatim} \end{small} Note the usage of ``MAXBLOCKSIZE''. In Libtomcrypt no symmetric block, key or hash digest is larger than MAXBLOCKSIZE in length. This provides a simple size you can set your automatic arrays to that will not get overrun. There are three helper functions as well: \index{hash\_memory()} \index{hash\_file()} \begin{verbatim} int hash_memory(int hash, const unsigned char *data, unsigned long len, unsigned char *dst, unsigned long *outlen); int hash_file(int hash, const char *fname, unsigned char *dst, unsigned long *outlen); int hash_filehandle(int hash, FILE *in, unsigned char *dst, unsigned long *outlen); \end{verbatim} The ``hash'' parameter is the location in the descriptor table of the hash (\textit{e.g. the return of find\_hash()}). The ``*outlen'' variable is used to keep track of the output size. You must set it to the size of your output buffer before calling the functions. When they complete succesfully they store the length of the message digest back in it. The functions are otherwise straightforward. The ``hash\_filehandle'' function assumes that ``in'' is an file handle opened in binary mode. It will hash to the end of file and not reset the file position when finished. To perform the above hash with md5 the following code could be used: \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { int idx, err; unsigned long len; unsigned char out[MAXBLOCKSIZE]; /* register the hash */ if (register_hash(&md5_desc) == -1) { printf("Error registering MD5.\n"); return -1; } /* get the index of the hash */ idx = find_hash("md5"); /* call the hash */ len = sizeof(out); if ((err = hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) { printf("Error hashing data: %s\n", error_to_string(err)); return -1; } return 0; } \end{verbatim} \end{small} The following hashes are provided as of this release: \index{Hash descriptor table} \begin{center} \begin{tabular}{|c|c|c|} \hline Name & Descriptor Name & Size of Message Digest (bytes) \\ \hline WHIRLPOOL & whirlpool\_desc & 64 \\ \hline SHA-512 & sha512\_desc & 64 \\ \hline SHA-384 & sha384\_desc & 48 \\ \hline SHA-256 & sha256\_desc & 32 \\ \hline SHA-224 & sha224\_desc & 28 \\ \hline TIGER-192 & tiger\_desc & 24 \\ \hline SHA-1 & sha1\_desc & 20 \\ \hline RIPEMD-160 & rmd160\_desc & 20 \\ \hline RIPEMD-128 & rmd128\_desc & 16 \\ \hline MD5 & md5\_desc & 16 \\ \hline MD4 & md4\_desc & 16 \\ \hline MD2 & md2\_desc & 16 \\ \hline \end{tabular} \end{center} Similar to the cipher descriptor table you must register your hash algorithms before you can use them. These functions work exactly like those of the cipher registration code. The functions are: \index{register\_hash()} \index{unregister\_hash()} \begin{verbatim} int register_hash(const struct _hash_descriptor *hash); int unregister_hash(const struct _hash_descriptor *hash); \end{verbatim} \subsection{Notice} It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes. These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators (e.g. Yarrow). The other hashes such as the SHA-1, SHA-2 (that includes SHA-512, SHA-384 and SHA-256) and TIGER-192 are still considered secure for all purposes you would normally use a hash for. \chapter{Message Authentication Codes} \section{HMAC Protocol} Thanks to Dobes Vandermeer the library now includes support for hash based message authenication codes or HMAC for short. An HMAC of a message is a keyed authenication code that only the owner of a private symmetric key will be able to verify. The purpose is to allow an owner of a private symmetric key to produce an HMAC on a message then later verify if it is correct. Any impostor or eavesdropper will not be able to verify the authenticity of a message. The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key and its length. The key is much like a key you would pass to a cipher. That is, it is simply an array of octets stored in chars. The initialization routine is: \index{hmac\_init()} \begin{verbatim} int hmac_init(hmac_state *hmac, int hash, const unsigned char *key, unsigned long keylen); \end{verbatim} The ``hmac'' parameter is the state for the HMAC code. ``hash'' is the index into the descriptor table of the hash you want to use to authenticate the message. ``key'' is the pointer to the array of chars that make up the key. ``keylen'' is the length (in octets) of the key you want to use to authenticate the message. To send octets of a message through the HMAC system you must use the following function: \index{hmac\_process()} \begin{verbatim} int hmac_process(hmac_state *hmac, const unsigned char *buf, unsigned long len); \end{verbatim} ``hmac'' is the HMAC state you are working with. ``buf'' is the array of octets to send into the HMAC process. ``len'' is the number of octets to process. Like the hash process routines you can send the data in arbitrarly sized chunks. When you are finished with the HMAC process you must call the following function to get the HMAC code: \index{hmac\_done()} \begin{verbatim} int hmac_done(hmac_state *hmac, unsigned char *hashOut, unsigned long *outlen); \end{verbatim} ``hmac'' is the HMAC state you are working with. ``hashOut'' is the array of octets where the HMAC code should be stored. You must set ``outlen'' to the size of the destination buffer before calling this function. It is updated with the length of the HMAC code produced (depending on which hash was picked). If ``outlen'' is less than the size of the message digest (and ultimately the HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first ``outlen'' bytes). There are two utility functions provided to make using HMACs easier todo. They accept the key and information about the message (file pointer, address in memory) and produce the HMAC result in one shot. These are useful if you want to avoid calling the three step process yourself. \index{hmac\_memory()} \begin{verbatim} int hmac_memory(int hash, const unsigned char *key, unsigned long keylen, const unsigned char *data, unsigned long len, unsigned char *dst, unsigned long *dstlen); \end{verbatim} This will produce an HMAC code for the array of octets in ``data'' of length ``len''. The index into the hash descriptor table must be provided in ``hash''. It uses the key from ``key'' with a key length of ``keylen''. The result is stored in the array of octets ``dst'' and the length in ``dstlen''. The value of ``dstlen'' must be set to the size of the destination buffer before calling this function. Similarly for files there is the following function: \index{hmac\_file()} \begin{verbatim} int hmac_file(int hash, const char *fname, const unsigned char *key, unsigned long keylen, unsigned char *dst, unsigned long *dstlen); \end{verbatim} ``hash'' is the index into the hash descriptor table of the hash you want to use. ``fname'' is the filename to process. ``key'' is the array of octets to use as the key of length ``keylen''. ``dst'' is the array of octets where the result should be stored. To test if the HMAC code is working there is the following function: \index{hmac\_test()} \begin{verbatim} int hmac_test(void); \end{verbatim} Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the HMAC system is given below. \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { int idx, err; hmac_state hmac; unsigned char key[16], dst[MAXBLOCKSIZE]; unsigned long dstlen; /* register SHA-1 */ if (register_hash(&sha1_desc) == -1) { printf("Error registering SHA1\n"); return -1; } /* get index of SHA1 in hash descriptor table */ idx = find_hash("sha1"); /* we would make up our symmetric key in "key[]" here */ /* start the HMAC */ if ((err = hmac_init(&hmac, idx, key, 16)) != CRYPT_OK) { printf("Error setting up hmac: %s\n", error_to_string(err)); return -1; } /* process a few octets */ if((err = hmac_process(&hmac, "hello", 5) != CRYPT_OK) { printf("Error processing hmac: %s\n", error_to_string(err)); return -1; } /* get result (presumably to use it somehow...) */ dstlen = sizeof(dst); if ((err = hmac_done(&hmac, dst, &dstlen)) != CRYPT_OK) { printf("Error finishing hmac: %s\n", error_to_string(err)); return -1; } printf("The hmac is %lu bytes long\n", dstlen); /* return */ return 0; } \end{verbatim} \end{small} \section{OMAC Support} OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an algorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES. From an API standpoint the OMAC routines work much like the HMAC routines do. Instead in this case a cipher is used instead of a hash. To start an OMAC state you call \index{omac\_init()} \begin{verbatim} int omac_init(omac_state *omac, int cipher, const unsigned char *key, unsigned long keylen); \end{verbatim} The ``omac'' variable is the state for the OMAC algorithm. ``cipher'' is the index into the cipher\_descriptor table of the cipher\footnote{The cipher must have a 64 or 128 bit block size. Such as CAST5, Blowfish, DES, AES, Twofish, etc.} you wish to use. ``key'' and ``keylen'' are the keys used to authenticate the data. To send data through the algorithm call \index{omac\_process()} \begin{verbatim} int omac_process(omac_state *state, const unsigned char *buf, unsigned long len); \end{verbatim} This will send ``len'' bytes from ``buf'' through the active OMAC state ``state''. Returns \textbf{CRYPT\_OK} if the function succeeds. The function is not sensitive to the granularity of the data. For example, \begin{verbatim} omac_process(&mystate, "hello", 5); omac_process(&mystate, " world", 6); \end{verbatim} Would produce the same result as, \begin{verbatim} omac_process(&mystate, "hello world", 11); \end{verbatim} When you are done processing the message you can call the following to compute the message tag. \index{omac\_done()} \begin{verbatim} int omac_done(omac_state *state, unsigned char *out, unsigned long *outlen); \end{verbatim} Which will terminate the OMAC and output the \textit{tag} (MAC) to ``out''. Note that unlike the HMAC and other code ``outlen'' can be smaller than the default MAC size (for instance AES would make a 16-byte tag). Part of the OMAC specification states that the output may be truncated. So if you pass in $outlen = 5$ and use AES as your cipher than the output MAC code will only be five bytes long. If ``outlen'' is larger than the default size it is set to the default size to show how many bytes were actually used. Similar to the HMAC code the file and memory functions are also provided. To OMAC a buffer of memory in one shot use the following function. \index{omac\_memory()} \begin{verbatim} int omac_memory(int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *msg, unsigned long msglen, unsigned char *out, unsigned long *outlen); \end{verbatim} This will compute the OMAC of ``msglen'' bytes of ``msg'' using the key ``key'' of length ``keylen'' bytes and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with the same rules as omac\_done. To OMAC a file use \index{omac\_file()} \begin{verbatim} int omac_file(int cipher, const unsigned char *key, unsigned long keylen, const char *filename, unsigned char *out, unsigned long *outlen); \end{verbatim} Which will OMAC the entire contents of the file specified by ``filename'' using the key ``key'' of length ``keylen'' bytes and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with the same rules as omac\_done. To test if the OMAC code is working there is the following function: \index{omac\_test()} \begin{verbatim} int omac_test(void); \end{verbatim} Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the OMAC system is given below. \begin{small} \begin{verbatim} #include <mycrypt.h> int main(void) { int idx, err; omac_state omac; unsigned char key[16], dst[MAXBLOCKSIZE]; unsigned long dstlen; /* register Rijndael */ if (register_cipher(&rijndael_desc) == -1) { printf("Error registering Rijndael\n"); return -1; } /* get index of Rijndael in cipher descriptor table */ idx = find_cipher("rijndael"); /* we would make up our symmetric key in "key[]" here */ /* start the OMAC */ if ((err = omac_init(&omac, idx, key, 16)) != CRYPT_OK) { printf("Error setting up omac: %s\n", error_to_string(err)); return -1; } /* process a few octets */ if((err = omac_process(&omac, "hello", 5) != CRYPT_OK) { printf("Error processing omac: %s\n", error_to_string(err)); return -1; } /* get result (presumably to use it somehow...) */ dstlen = sizeof(dst); if ((err = omac_done(&omac, dst, &dstlen)) != CRYPT_OK) { printf("Error finishing omac: %s\n", error_to_string(err)); return -1; } printf("The omac is %lu bytes long\n", dstlen); /* return */ return 0; } \end{verbatim} \end{small} \section{PMAC Support} The PMAC\footnote{J.Black, P.Rogaway, ``A Block--Cipher Mode of Operation for Parallelizable Message Authentication''} protocol is another MAC algorithm that relies solely on a symmetric-key block cipher. It uses essentially the same API as the provided OMAC code. A PMAC state is initialized with the following. \index{pmac\_init()} \begin{verbatim} int pmac_init(pmac_state *pmac, int cipher, const unsigned char *key, unsigned long keylen); \end{verbatim} Which initializes the ``pmac'' state with the given ``cipher'' and ``key'' of length ``keylen'' bytes. The chosen cipher must have a 64 or 128 bit block size (e.x. AES). To MAC data simply send it through the process function. \index{pmac\_process()} \begin{verbatim} int pmac_process(pmac_state *state, const unsigned char *buf, unsigned long len); \end{verbatim} This will process ``len'' bytes of ``buf'' in the given ``state''. The function is not sensitive to the granularity of the data. For example, \begin{verbatim} pmac_process(&mystate, "hello", 5); pmac_process(&mystate, " world", 6); \end{verbatim} Would produce the same result as, \begin{verbatim} pmac_process(&mystate, "hello world", 11); \end{verbatim} When a complete message has been processed the following function can be called to compute the message tag. \index{pmac\_done()} \begin{verbatim} int pmac_done(pmac_state *state, unsigned char *out, unsigned long *outlen); \end{verbatim} This will store upto ``outlen'' bytes of the tag for the given ``state'' into ``out''. Note that if ``outlen'' is larger than the size of the tag it is set to the amount of bytes stored in ``out''. Similar to the PMAC code the file and memory functions are also provided. To PMAC a buffer of memory in one shot use the following function. \index{pmac\_memory()} \begin{verbatim} int pmac_memory(int cipher, const unsigned char *key, unsigned long keylen, const unsigned char *msg, unsigned long msglen, unsigned char *out, unsigned long *outlen); \end{verbatim} This will compute the PMAC of ``msglen'' bytes of ``msg'' using the key ``key'' of length ``keylen'' bytes and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with the same rules as omac\_done. To PMAC a file use \index{pmac\_file()} \begin{verbatim} int pmac_file(int cipher, const unsigned char *key, unsigned long keylen, const char *filename, unsigned char *out, unsigned long *outlen); \end{verbatim} Which will PMAC the entire contents of the file specified by ``filename'' using the key ``key'' of length ``keylen'' bytes and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with the same rules as omac\_done. To test if the PMAC code is working there is the following function: \begin{verbatim} int pmac_test(void); \end{verbatim} Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. \chapter{Pseudo-Random Number Generators} \section{Core Functions} The library provides an array of core functions for Pseudo-Random Number Generators (PRNGs) as well. A cryptographic PRNG is used to expand a shorter bit string into a longer bit string. PRNGs are used wherever random data is required such as Public Key (PK) key generation. There is a universal structure called ``prng\_state''. To initialize a PRNG call: \begin{verbatim} int XXX_start(prng_state *prng); \end{verbatim} This will setup the PRNG for future use and not seed it. In order for the PRNG to be cryptographically useful you must give it entropy. Ideally you'd have some OS level source to tap like in UNIX (see section 5.3). To add entropy to the PRNG call: \begin{verbatim} int XXX_add_entropy(const unsigned char *in, unsigned long len, prng_state *prng); \end{verbatim} Which returns {\bf CRYPTO\_OK} if the entropy was accepted. Once you think you have enough entropy you call another function to put the entropy into action. \begin{verbatim} int XXX_ready(prng_state *prng); \end{verbatim} Which returns {\bf CRYPTO\_OK} if it is ready. Finally to actually read bytes call: \begin{verbatim} unsigned long