3143 lines
144 KiB
TeX
3143 lines
144 KiB
TeX
\documentclass[a4paper]{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{LibTomCrypt \\ Version 0.97a}
|
|
\author{Tom St Denis \\
|
|
\\
|
|
tomstdenis@iahu.ca \\
|
|
http://libtomcrypt.org
|
|
}
|
|
\maketitle
|
|
This text and source code library are both hereby placed in the public domain. This book has been
|
|
formatted for A4 paper using the \LaTeX{} {\em book} macro package.
|
|
|
|
\vspace{10cm}
|
|
|
|
\begin{flushright}Open Source. Open Academia. Open Minds.
|
|
|
|
\mbox{ }
|
|
|
|
Tom St Denis,
|
|
|
|
Phone: 1-613-836-3160
|
|
|
|
111 Banning Rd
|
|
|
|
Kanata, Ontario
|
|
|
|
K2L 1C3
|
|
|
|
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 seems to be free for use.
|
|
|
|
The project is hereby released as public domain.
|
|
|
|
\section{Patent Disclosure}
|
|
|
|
The author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice. To the best
|
|
of the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers.
|
|
They can be removed from a build by simply commenting out the two appropriate lines in ``mycrypt\_custom.h''. The rest
|
|
of the ciphers and hashes are patent free or under patents that have since expired.
|
|
|
|
The RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations. This means you can use
|
|
the ciphers you just can't advertise that you are doing so.
|
|
|
|
\section{Building the library}
|
|
|
|
To build the library on a GCC equipped platform simply type ``make'' at your command prompt. It will build the library
|
|
file ``libtomcrypt.a''.
|
|
|
|
To install the library copy all of the ``.h'' files into your ``\#include'' path and the single libtomcrypt.a file into
|
|
your library path.
|
|
|
|
With MSVC you can build the library with ``nmake -f makefile.msvc''. This will produce a ``tomcrypt.lib'' file which
|
|
is the core library. Copy the header files into your MSVC include path and the library in the lib path (typically
|
|
under where VC98 is installed).
|
|
|
|
\section{Building against the library}
|
|
|
|
In the recent versions the build steps have changed. The build options are now stored in ``mycrypt\_custom.h'' and
|
|
no longer in the makefile. If you change a build option in that file you must re-build the library from clean to
|
|
ensure the build is intact.
|
|
|
|
\section{Thanks}
|
|
I would like to give thanks to the following people (in no particular order) for helping me develop this project from
|
|
early on:
|
|
\begin{enumerate}
|
|
\item Richard van de Laarschot
|
|
\item Richard Heathfield
|
|
\item Ajay K. Agrawal
|
|
\item Brian Gladman
|
|
\item 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}
|
|
|
|
There have been quite a few other people as well. Please check the change log to see who else has contributed from
|
|
time to time.
|
|
|
|
|
|
\chapter{The Application Programming Interface (API)}
|
|
\section{Introduction}
|
|
\index{CRYPT\_ERROR} \index{CRYPT\_OK}
|
|
|
|
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 & Faster keysetup, larger code. \\
|
|
\hline defined & undefined & Very slow, 0.2KB of ram. \\
|
|
\hline defined & defined & 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 XXX_read(unsigned char *out, unsigned long len,
|
|
prng_state *prng);
|
|
\end{verbatim}
|
|
|
|
Which returns the number of bytes read from the PRNG.
|
|
|
|
\subsection{Remarks}
|
|
|
|
It is possible to be adding entropy and reading from a PRNG at the same time. For example, if you first seed the PRNG
|
|
and call ready() you can now read from it. You can also keep adding new entropy to it. The new entropy will not be used
|
|
in the PRNG until ready() is called again. This allows the PRNG to be used and re-seeded at the same time. No real error
|
|
checking is guaranteed to see if the entropy is sufficient or if the PRNG is even in a ready state before reading.
|
|
|
|
\subsection{Example}
|
|
|
|
Below is a simple snippet to read 10 bytes from yarrow. Its important to note that this snippet is {\bf NOT} secure since
|
|
the entropy added is not random.
|
|
|
|
\begin{verbatim}
|
|
#include <mycrypt.h>
|
|
int main(void)
|
|
{
|
|
prng_state prng;
|
|
unsigned char buf[10];
|
|
int err;
|
|
|
|
/* start it */
|
|
if ((err = yarrow_start(&prng)) != CRYPT_OK) {
|
|
printf("Start error: %s\n", error_to_string(err));
|
|
}
|
|
/* add entropy */
|
|
if ((err = yarrow_add_entropy("hello world", 11, &prng)) != CRYPT_OK) {
|
|
printf("Add_entropy error: %s\n", error_to_string(err));
|
|
}
|
|
/* ready and read */
|
|
if ((err = yarrow_ready(&prng)) != CRYPT_OK) {
|
|
printf("Ready error: %s\n", error_to_string(err));
|
|
}
|
|
printf("Read %lu bytes from yarrow\n", yarrow_read(buf, 10, &prng));
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
|
|
\section{PRNG Descriptors}
|
|
\index{PRNG Descriptor}
|
|
PRNGs have descriptors too (surprised?). Stored in the structure ``prng\_descriptor''. The format of an element is:
|
|
\begin{verbatim}
|
|
struct _prng_descriptor {
|
|
char *name;
|
|
int (*start) (prng_state *);
|
|
int (*add_entropy)(const unsigned char *, unsigned long, prng_state *);
|
|
int (*ready) (prng_state *);
|
|
unsigned long (*read)(unsigned char *, unsigned long len, prng_state *);
|
|
};
|
|
\end{verbatim}
|
|
|
|
There is a ``int find\_prng(char *name)'' function as well. Returns -1 if the PRNG is not found, otherwise it returns
|
|
the position in the prng\_descriptor array.
|
|
|
|
Just like the ciphers and hashes you must register your prng before you can use it. The two functions provided work
|
|
exactly as those for the cipher registry functions. They are:
|
|
\begin{verbatim}
|
|
int register_prng(const struct _prng_descriptor *prng);
|
|
int unregister_prng(const struct _prng_descriptor *prng);
|
|
\end{verbatim}
|
|
|
|
\subsubsection{PRNGs Provided}
|
|
Currently Yarrow (yarrow\_desc), RC4 (rc4\_desc) and the secure RNG (sprng\_desc) are provided as PRNGs within the
|
|
library.
|
|
|
|
RC4 is provided with a PRNG interface because it is a stream cipher and not well suited for the symmetric block cipher
|
|
interface. You provide the key for RC4 via the rc4\_add\_entropy() function. By calling rc4\_ready() the key will be used
|
|
to setup the RC4 state for encryption or decryption. The rc4\_read() function has been modified from RC4 since it will
|
|
XOR the output of the RC4 keystream generator against the input buffer you provide. The following snippet will demonstrate
|
|
how to encrypt a buffer with RC4:
|
|
|
|
\begin{small}
|
|
\begin{verbatim}
|
|
#include <mycrypt.h>
|
|
int main(void)
|
|
{
|
|
prng_state prng;
|
|
unsigned char buf[32];
|
|
int err;
|
|
|
|
if ((err = rc4_start(&prng)) != CRYPT_OK) {
|
|
printf("RC4 init error: %s\n", error_to_string(err));
|
|
exit(-1);
|
|
}
|
|
|
|
/* use ``key'' as the key */
|
|
if ((err = rc4_add_entropy("key", 3, &prng)) != CRYPT_OK) {
|
|
printf("RC4 add entropy error: %s\n", error_to_string(err));
|
|
exit(-1);
|
|
}
|
|
|
|
/* setup RC4 for use */
|
|
if ((err = rc4_ready(&prng)) != CRYPT_OK) {
|
|
printf("RC4 ready error: %s\n", error_to_string(err));
|
|
exit(-1);
|
|
}
|
|
|
|
/* encrypt buffer */
|
|
strcpy(buf,"hello world");
|
|
if (rc4_read(buf, 11, &prng) != 11) {
|
|
printf("RC4 read error\n");
|
|
exit(-1);
|
|
}
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
\end{small}
|
|
To decrypt you have to do the exact same steps.
|
|
|
|
\section{The Secure RNG}
|
|
\index{Secure RNG}
|
|
An RNG is related to a PRNG except that it doesn't expand a smaller seed to get the data. They generate their random bits
|
|
by performing some computation on fresh input bits. Possibly the hardest thing to get correctly in a cryptosystem is the
|
|
PRNG. Computers are deterministic beasts that try hard not to stray from pre-determined paths. That makes gathering
|
|
entropy needed to seed the PRNG a hard task.
|
|
|
|
There is one small function that may help on certain platforms:
|
|
\index{rng\_get\_bytes()}
|
|
\begin{verbatim}
|
|
unsigned long rng_get_bytes(unsigned char *buf, unsigned long len,
|
|
void (*callback)(void));
|
|
\end{verbatim}
|
|
|
|
Which will try one of three methods of getting random data. The first is to open the popular ``/dev/random'' device which
|
|
on most *NIX platforms provides cryptographic random bits\footnote{This device is available in Windows through the Cygwin compiler suite. It emulates ``/dev/random'' via the Microsoft CSP.}.
|
|
The second method is to try the Microsoft Cryptographic Service Provider and read the RNG. The third method is an ANSI C
|
|
clock drift method that is also somewhat popular but gives bits of lower entropy. The ``callback'' parameter is a pointer to a function that returns void. Its used when the slower ANSI C RNG must be
|
|
used so the calling application can still work. This is useful since the ANSI C RNG has a throughput of three
|
|
bytes a second. The callback pointer may be set to {\bf NULL} to avoid using it if you don't want to. The function
|
|
returns the number of bytes actually read from any RNG source. There is a function to help setup a PRNG as well:
|
|
\index{rng\_make\_prng()}
|
|
\begin{verbatim}
|
|
int rng_make_prng(int bits, int wprng, prng_state *prng,
|
|
void (*callback)(void));
|
|
\end{verbatim}
|
|
This will try to setup the prng with a state of at least ``bits'' of entropy. The ``callback'' parameter works much like
|
|
the callback in ``rng\_get\_bytes()''. It is highly recommended that you use this function to setup your PRNGs unless you have a
|
|
platform where the RNG doesn't work well. Example usage of this function is given below.
|
|
|
|
\begin{small}
|
|
\begin{verbatim}
|
|
#include <mycrypt.h>
|
|
int main(void)
|
|
{
|
|
ecc_key mykey;
|
|
prng_state prng;
|
|
int err;
|
|
|
|
/* register yarrow */
|
|
if (register_prng(&yarrow_desc) == -1) {
|
|
printf("Error registering Yarrow\n");
|
|
return -1;
|
|
}
|
|
|
|
/* setup the PRNG */
|
|
if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) != CRYPT_OK) {
|
|
printf("Error setting up PRNG, %s\n", error_to_string(err));
|
|
return -1;
|
|
}
|
|
|
|
/* make a 192-bit ECC key */
|
|
if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) != CRYPT_OK) {
|
|
printf("Error making key: %s\n", error_to_string(err));
|
|
return -1;
|
|
}
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
\end{small}
|
|
|
|
\subsection{The Secure PRNG Interface}
|
|
It is possible to access the secure RNG through the PRNG interface and in turn use it within dependent functions such
|
|
as the PK API. This simplifies the cryptosystem on platforms where the secure RNG is fast. The secure PRNG never
|
|
requires to be started, that is you need not call the start, add\_entropy or ready functions. For example, consider
|
|
the previous example using this PRNG.
|
|
|
|
\begin{small}
|
|
\begin{verbatim}
|
|
#include <mycrypt.h>
|
|
int main(void)
|
|
{
|
|
ecc_key mykey;
|
|
int err;
|
|
|
|
/* register SPRNG */
|
|
if (register_prng(&sprng_desc) == -1) {
|
|
printf("Error registering SPRNG\n");
|
|
return -1;
|
|
}
|
|
|
|
/* make a 192-bit ECC key */
|
|
if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) != CRYPT_OK) {
|
|
printf("Error making key: %s\n", error_to_string(err));
|
|
return -1;
|
|
}
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
\end{small}
|
|
|
|
\chapter{RSA Public Key Cryptography}
|
|
|
|
\section{Introduction}
|
|
RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are
|
|
padding algorithms for encryption and signatures. The standard includes ``v1.5'' and ``v2.0'' algorithms.
|
|
To simplify matters a little the v2.0 encryption and signature padding algorithms are called OAEP and PSS
|
|
respectively.
|
|
|
|
\section{PKCS \#1 Encryption}
|
|
|
|
PKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation. As far as this portion of
|
|
the library is concerned we are only dealing with th OAEP padding of the message.
|
|
|
|
\subsection{OAEP Encoding}
|
|
|
|
\index{pkcs\_1\_oaep\_encode()}
|
|
\begin{alltt}
|
|
int pkcs_1_oaep_encode(const unsigned char *msg, unsigned long msglen,
|
|
const unsigned char *lparam, unsigned long lparamlen,
|
|
unsigned long modulus_bitlen, prng_state *prng,
|
|
int prng_idx, int hash_idx,
|
|
unsigned char *out, unsigned long *outlen);
|
|
\end{alltt}
|
|
|
|
This accepts ``msg'' as input of length ``msglen'' which will be OAEP padded. The ``lparam'' variable is an additional system specific
|
|
tag that can be applied to the encoding. This is useful to identify which system encoded the message. If no variance is desired then
|
|
``lparam'' can be set to \textbf{NULL}.
|
|
|
|
OAEP encoding requires the length of the modulus in bits in order to calculate the size of the output. This is passed as the parameter
|
|
``modulus\_bitlen''. ``hash\_idx'' is the index into the hash descriptor table of the hash desired. PKCS \#1 allows any hash to be
|
|
used but both the encoder and decoder must use the same hash in order for this to succeed. The size of hash output affects the maximum
|
|
sized input message. ``prng\_idx'' and ``prng'' are the random number generator arguments required to randomize the padding process.
|
|
The padded message is stored in ``out'' along with the length in ``outlen''.
|
|
|
|
If $h$ is the length of the hash and $m$ the length of the modulus (both in octets) then the maximum payload for ``msg'' is
|
|
$m - 2h - 2$. For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes.
|
|
|
|
Note that when the message is padded it still has not been RSA encrypted. You must pass the output of this function to
|
|
rsa\_exptmod() to encrypt it.
|
|
|
|
\subsection{OAEP Decoding}
|
|
|
|
\index{pkcs\_1\_oaep\_decode()}
|
|
\begin{alltt}
|
|
int pkcs_1_oaep_decode(const unsigned char *msg, unsigned long msglen,
|
|
const unsigned char *lparam, unsigned long lparamlen,
|
|
unsigned long modulus_bitlen, int hash_idx,
|
|
unsigned char *out, unsigned long *outlen,
|
|
int *res);
|
|
\end{alltt}
|
|
|
|
This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. ``msg'' is the
|
|
output of pkcs\_1\_oaep\_encode() of length ``msglen''. ``lparam'' is the same system variable passed to the OAEP encoder. If it does not
|
|
match what was used during encoding this function will not decode the packet. ``modulus\_bitlen'' is the size of the RSA modulus in bits
|
|
and must match what was used during encoding. Similarly the ``hash\_idx'' index into the hash descriptor table must match what was used
|
|
during encoding.
|
|
|
|
If the function succeeds it decodes the OAEP encoded message into ``out'' of length ``outlen'' and stores a
|
|
$1$ in ``res''. If the packet is invalid it stores $0$ in ``res'' and if the function fails for another reason
|
|
it returns an error code.
|
|
|
|
\subsection{PKCS \#1 v1.5 Encoding}
|
|
|
|
\index{pkcs\_1\_v15\_es\_encode()}
|
|
\begin{verbatim}
|
|
int pkcs_1_v15_es_encode(const unsigned char *msg, unsigned long msglen,
|
|
unsigned long modulus_bitlen,
|
|
prng_state *prng, int prng_idx,
|
|
unsigned char *out, unsigned long *outlen);
|
|
\end{verbatim}
|
|
|
|
This will PKCS v1.5 encode the data in ``msg'' of length ``msglen''. Pass the length (in bits) of your
|
|
RSA modulus in ``modulus\_bitlen''. The encoded data will be stored in ``out'' of length ``outlen''.
|
|
|
|
\subsection{PKCS \#1 v1.5 Decoding}
|
|
\index{pkcs\_1\_v15\_es\_decode()}
|
|
\begin{verbatim}
|
|
int pkcs_1_v15_es_decode(const unsigned char *msg, unsigned long msglen,
|
|
unsigned long modulus_bitlen,
|
|
unsigned char *out, unsigned long outlen,
|
|
int *res);
|
|
\end{verbatim}
|
|
|
|
This will PKCS v1.5 decode the message in ``msg'' of length ``msglen''. It will store the output in ``out''. Note
|
|
that the length of the output ``outlen'' is a constant. This decoder cannot determine the original message
|
|
length. If the data in ``msg'' is a valid packet then a $1$ is stored in ``res'', otherwise a $0$ is
|
|
stored.
|
|
|
|
\section{PKCS \#1 Digital Signatures}
|
|
|
|
\subsection{PSS Encoding}
|
|
PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed.
|
|
|
|
\index{pkcs\_1\_pss\_encode()}
|
|
\begin{alltt}
|
|
int pkcs_1_pss_encode(const unsigned char *msghash, unsigned long msghashlen,
|
|
unsigned long saltlen, prng_state *prng,
|
|
int prng_idx, int hash_idx,
|
|
unsigned long modulus_bitlen,
|
|
unsigned char *out, unsigned long *outlen);
|
|
\end{alltt}
|
|
|
|
This function assumes the message to be PSS encoded has previously been hashed. The input hash ``msghash'' is of length
|
|
``msghashlen''. PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process.
|
|
``hash\_idx'' is the index into the hash descriptor table of the hash to use. ``prng\_idx'' and ``prng'' are the random
|
|
number generator information required for the salt.
|
|
|
|
Similar to OAEP encoding ``modulus\_bitlen'' is the size of the RSA modulus (in bits). It limits the size of the salt. If $m$ is the length
|
|
of the modulus $h$ the length of the hash output (in octets) then there can be $m - h - 2$ bytes of salt.
|
|
|
|
This function does not actually sign the data it merely pads the hash of a message so that it can be processed by rsa\_exptmod().
|
|
|
|
\subsection{PSS Decoding}
|
|
|
|
To decode a PSS encoded signature block you have to use the following.
|
|
|
|
\index{pkcs\_1\_pss\_decode()}
|
|
\begin{alltt}
|
|
int pkcs_1_pss_decode(const unsigned char *msghash, unsigned long msghashlen,
|
|
const unsigned char *sig, unsigned long siglen,
|
|
unsigned long saltlen, int hash_idx,
|
|
unsigned long modulus_bitlen, int *res);
|
|
\end{alltt}
|
|
This will decode the PSS encoded message in ``sig'' of length ``siglen'' and compare it to values in ``msghash'' of length
|
|
``msghashlen''. If the block is a valid PSS block and the decoded hash equals the hash supplied ``res'' is set to non--zero. Otherwise,
|
|
it is set to zero. The rest of the parameters are as in the PSS encode call.
|
|
|
|
It's important to use the same ``saltlen'' and hash for both encoding and decoding as otherwise the procedure will not work.
|
|
|
|
\subsection{PKCS \#1 v1.5 Encoding}
|
|
|
|
\index{pkcs\_1\_v15\_sa\_encode()}
|
|
\begin{verbatim}
|
|
int pkcs_1_v15_sa_encode(const unsigned char *msghash, unsigned long msghashlen,
|
|
int hash_idx, unsigned long modulus_bitlen,
|
|
unsigned char *out, unsigned long *outlen);
|
|
\end{verbatim}
|
|
|
|
This will PKCS \#1 v1.5 signature encode the message hash ``msghash'' of length ``msghashlen''. You have
|
|
to tell this routine which hash produced the message hash in ``hash\_idx''. The encoded hash is stored
|
|
in ``out'' of length ``outlen''.
|
|
|
|
\subsection{PKCS \#1 v1.5 Decoding}
|
|
|
|
\index{pkcs\_1\_v15\_sa\_decode()}
|
|
\begin{verbatim}
|
|
int pkcs_1_v15_sa_decode(const unsigned char *msghash, unsigned long msghashlen,
|
|
const unsigned char *sig, unsigned long siglen,
|
|
int hash_idx, unsigned long modulus_bitlen,
|
|
int *res);
|
|
\end{verbatim}
|
|
|
|
This will PKCS \#1 v1.5 signature decode the data in ``sig'' of length ``siglen'' and compare the extracted
|
|
hash against ``msghash'' of length ``msghashlen''. You have to tell this routine which hash produced the
|
|
message digest in ``hash\_idx''. If the packet is valid and the hashes match ``res'' is set to $1$. Otherwise,
|
|
it is set to $0$.
|
|
|
|
\section{RSA Operations}
|
|
\subsection{Background}
|
|
|
|
RSA is a public key algorithm that is based on the inability to find the ``e-th'' root modulo a composite of unknown
|
|
factorization. Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are
|
|
not strictly equivalent.
|
|
|
|
The system begins with with two primes $p$ and $q$ and their product $N = pq$. The order or ``Euler totient'' of the
|
|
multiplicative sub-group formed modulo $N$ is given as $\phi(N) = (p - 1)(q - 1)$ which can be reduced to
|
|
$\mbox{lcm}(p - 1, q - 1)$. The public key consists of the composite $N$ and some integer $e$ such that
|
|
$\mbox{gcd}(e, \phi(N)) = 1$. The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$
|
|
often simply denoted as $de \equiv 1\mbox{ }(\mbox{mod }\phi(N))$.
|
|
|
|
A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that
|
|
$1 < M < N-2$ and computes the ciphertext $C = M^e\mbox{ }(\mbox{mod }N)$. Since finding the inverse exponent $d$
|
|
given only $N$ and $e$ appears to be intractable only the owner of the private key can decrypt the ciphertext and compute
|
|
$C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key
|
|
can sign a message by ``decrypting'' it. Others can verify it by ``encrypting'' it.
|
|
|
|
Currently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other.
|
|
Ideally $e$ should be larger than $100$ to prevent direct analysis. For example, if $e$ is three and you do not pad
|
|
the plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial.
|
|
The most often suggested value for $e$ is $65537$ since it is large enough to make such attacks impossible and also well
|
|
designed for fast exponentiation (requires 16 squarings and one multiplication).
|
|
|
|
It is important to pad the input to RSA since it has particular mathematical structure. For instance
|
|
$M_1^dM_2^d = (M_1M_2)^d$ which can be used to forge a signature. Suppose $M_3 = M_1M_2$ is a message you want
|
|
to have a forged signature for. Simply get the signatures for $M_1$ and $M_2$ on their own and multiply the result
|
|
together. Similar tricks can be used to deduce plaintexts from ciphertexts. It is important not only to sign
|
|
the hash of documents only but also to pad the inputs with data to remove such structure.
|
|
|
|
\subsection{RSA Key Generation}
|
|
|
|
For RSA routines a single ``rsa\_key'' structure is used. To make a new RSA key call:
|
|
\index{rsa\_make\_key()}
|
|
\begin{verbatim}
|
|
int rsa_make_key(prng_state *prng,
|
|
int wprng, int size,
|
|
long e, rsa_key *key);
|
|
\end{verbatim}
|
|
|
|
Where ``wprng'' is the index into the PRNG descriptor array. ``size'' is the size in bytes of the RSA modulus desired.
|
|
``e'' is the encryption exponent desired, typical values are 3, 17, 257 and 65537. I suggest you stick with 65537 since its big
|
|
enough to prevent trivial math attacks and not super slow. ``key'' is where the key is placed. All keys must be at
|
|
least 128 bytes and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}).
|
|
|
|
Note that the ``rsa\_make\_key()'' function allocates memory at runtime when you make the key. Make sure to call
|
|
``rsa\_free()'' (see below) when you are finished with the key. If ``rsa\_make\_key()'' fails it will automatically
|
|
free the ram allocated itself.
|
|
|
|
There are three types of RSA keys. The types are {\bf PK\_PRIVATE\_OPTIMIZED}, {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}. The first
|
|
two are private keys where the ``optimized'' type uses the Chinese Remainder Theorem to speed up decryption/signatures. By
|
|
default all new keys are of the ``optimized'' type. The non-optimized private type is provided for backwards compatibility
|
|
as well as to save space since the optimized key requires about four times as much memory.
|
|
|
|
\subsection{RSA Exponentiation}
|
|
|
|
To do raw work with the RSA function call:
|
|
\index{rsa\_exptmod()}
|
|
\begin{verbatim}
|
|
int rsa_exptmod(const unsigned char *in, unsigned long inlen,
|
|
unsigned char *out, unsigned long *outlen, int which,
|
|
prng_state *prng, int prng_idx,
|
|
rsa_key *key);
|
|
\end{verbatim}
|
|
This loads the bignum from ``in'' as a big endian word in the format PKCS specifies, raises it to either ``e'' or ``d'' and stores the result
|
|
in ``out'' and the size of the result in ``outlen''. ``which'' is set to {\bf PK\_PUBLIC} to use ``e''
|
|
(i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use ``d'' as the exponent (i.e. for decrypting/signing).
|
|
|
|
Note that the output of his function is zero-padded as per PKCS \#1 specifications. This allows this routine to
|
|
interoprate with PKCS \#1 padding functions properly.
|
|
|
|
\subsection{RSA Key Encryption}
|
|
Normally RSA is used to encrypt short symmetric keys which are then used in block ciphers to encrypt a message.
|
|
To facilitate encrypting short keys the following functions have been provided.
|
|
|
|
\index{rsa\_encrypt\_key()}
|
|
\begin{verbatim}
|
|
int rsa_encrypt_key(const unsigned char *inkey, unsigned long inlen,
|
|
unsigned char *outkey, unsigned long *outlen,
|
|
const unsigned char *lparam, unsigned long lparamlen,
|
|
prng_state *prng, int prng_idx, int hash_idx, rsa_key *key);
|
|
\end{verbatim}
|
|
This function will OAEP pad ``inkey'' of length inlen bytes then RSA encrypt it and store the ciphertext
|
|
in ``outkey'' of length ``outlen''. The ``lparam'' and ``lparamlen'' are the same parameters you would pass
|
|
to pkcs\_1\_oaep\_encode().
|
|
|
|
\index{rsa\_decrypt\_key()}
|
|
\begin{verbatim}
|
|
int rsa_decrypt_key(const unsigned char *in, unsigned long inlen,
|
|
unsigned char *outkey, unsigned long *keylen,
|
|
const unsigned char *lparam, unsigned long lparamlen,
|
|
prng_state *prng, int prng_idx,
|
|
int hash_idx, int *res,
|
|
rsa_key *key);
|
|
\end{verbatim}
|
|
This function will RSA decrypt ``in'' of length ``inlen'' then OAEP depad the resulting data and store it in
|
|
``outkey'' of length ``outlen''. The ``lparam'' and ``lparamlen'' are the same parameters you would pass
|
|
to pkcs\_1\_oaep\_decode().
|
|
|
|
If the RSA decrypted data isn't a valid OAEP packet then ``res'' is set to $0$. Otherwise, it is set to $1$.
|
|
|
|
\subsection{RSA Hash Signatures}
|
|
Similar to RSA key encryption RSA is also used to ``digitally sign'' message digests (hashes). To facilitate this
|
|
process the following functions have been provided.
|
|
|
|
\index{rsa\_sign\_hash()}
|
|
\begin{verbatim}
|
|
int rsa_sign_hash(const unsigned char *msghash, unsigned long msghashlen,
|
|
unsigned char *sig, unsigned long *siglen,
|
|
prng_state *prng, int prng_idx,
|
|
int hash_idx, unsigned long saltlen,
|
|
rsa_key *key);
|
|
\end{verbatim}
|
|
|
|
This will PSS encode the message hash ``msghash'' of length ``msghashlen''. Next the PSS encoded message is
|
|
RSA ``signed'' and the output is stored in ``sig'' of length ``siglen''.
|
|
|
|
|
|
\index{rsa\_verify\_hash()}
|
|
\begin{verbatim}
|
|
int rsa_verify_hash(const unsigned char *sig, unsigned long siglen,
|
|
const unsigned char *msghash, unsigned long msghashlen,
|
|
prng_state *prng, int prng_idx,
|
|
int hash_idx, unsigned long saltlen,
|
|
int *stat, rsa_key *key);
|
|
\end{verbatim}
|
|
|
|
This will RSA ``verify'' the signature in ``sig'' of length ``siglen''. Next the RSA decoded data is PSS decoded
|
|
and the extracted hash is compared against the message hash ``msghash'' of length ``msghashlen''.
|
|
|
|
If the RSA decoded data is not a valid PSS message or if the PSS decoded hash does not match the ``msghash''
|
|
the value ``res'' is set to $0$. Otherwise, if the function succeeds and signature is valid ``res'' is set
|
|
to $1$.
|
|
|
|
\begin{verbatim}
|
|
#include <mycrypt.h>
|
|
int main(void)
|
|
{
|
|
int err, hash_idx, prng_idx, res;
|
|
unsigned long l1, l2;
|
|
unsigned char pt[16], pt2[16], out[1024];
|
|
rsa_key key;
|
|
|
|
/* register prng/hash */
|
|
if (register_prng(&sprng_desc) == -1) {
|
|
printf("Error registering sprng");
|
|
return EXIT_FAILURE;
|
|
}
|
|
|
|
if (register_hash(&sha1_desc) == -1) {
|
|
printf("Error registering sha1");
|
|
return EXIT_FAILURE;
|
|
}
|
|
hash_idx = find_hash("sha1");
|
|
prng_idx = find_prng("sprng");
|
|
|
|
/* make an RSA-1024 key */
|
|
if ((err = rsa_make_key(NULL, /* PRNG state */
|
|
prng_idx, /* PRNG idx */
|
|
1024/8, /* 1024-bit key */
|
|
65537, /* we like e=65537 */
|
|
&key) /* where to store the key */
|
|
) != CRYPT_OK) {
|
|
printf("rsa_make_key %s", error_to_string(err));
|
|
return EXIT_FAILURE;
|
|
}
|
|
|
|
/* fill in pt[] with a key we want to send ... */
|
|
l1 = sizeof(out);
|
|
if ((err = rsa_encrypt_key(pt, /* data we wish to encrypt */
|
|
16, /* data is 16 bytes long */
|
|
out, /* where to store ciphertext */
|
|
&l1, /* length of ciphertext */
|
|
"TestApp", /* our lparam for this program */
|
|
7, /* lparam is 7 bytes long */
|
|
NULL, /* PRNG state */
|
|
prng_idx, /* prng idx */
|
|
hash_idx, /* hash idx */
|
|
&key) /* our RSA key */
|
|
) != CRYPT_OK) {
|
|
printf("rsa_encrypt_key %s", error_to_string(err));
|
|
return EXIT_FAILURE;
|
|
}
|
|
|
|
/* now let's decrypt the encrypted key */
|
|
l2 = sizeof(pt2);
|
|
if ((err = rsa_decrypt_key(out, /* encrypted data */
|
|
l1, /* length of ciphertext */
|
|
pt2, /* where to put plaintext */
|
|
&l2, /* plaintext length */
|
|
"TestApp", /* lparam for this program */
|
|
7, /* lparam is 7 bytes long */
|
|
NULL, /* PRNG state */
|
|
prng_idx, /* prng idx */
|
|
hash_idx, /* hash idx */
|
|
&res, /* validity of data */
|
|
&key) /* our RSA key */
|
|
) != CRYPT_OK) {
|
|
printf("rsa_decrypt_key %s", error_to_string(err));
|
|
return EXIT_FAILURE;
|
|
}
|
|
/* if all went well pt == pt2, l2 == 16, res == 1 */
|
|
}
|
|
\end{verbatim}
|
|
|
|
\chapter{Password Based Cryptography}
|
|
\section{PKCS \#5}
|
|
In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted. PKCS \#5
|
|
is made up of two algorithms, Algorithm One and Algorithm Two. Algorithm One is the older fairly limited algorithm which has been implemented
|
|
for completeness. Algorithm Two is a bit more modern and more flexible to work with.
|
|
|
|
\section{Algorithm One}
|
|
Algorithm One accepts as input a password, an 8--byte salt and an iteration counter. The iteration counter is meant to act as delay for
|
|
people trying to brute force guess the password. The higher the iteration counter the longer the delay. This algorithm also requires a hash
|
|
algorithm and produces an output no longer than the output of the hash.
|
|
|
|
\index{pkcs\_5\_alg1()}
|
|
\begin{alltt}
|
|
int pkcs_5_alg1(const unsigned char *password, unsigned long password_len,
|
|
const unsigned char *salt,
|
|
int iteration_count, int hash_idx,
|
|
unsigned char *out, unsigned long *outlen)
|
|
\end{alltt}
|
|
Where ``password'' is the users password. Since the algorithm allows binary passwords you must also specify the length in ``password\_len''.
|
|
The ``salt'' is a fixed size 8--byte array which should be random for each user and session. The ``iteration\_count'' is the delay desired
|
|
on the password. The ``hash\_idx'' is the index of the hash you wish to use in the descriptor table.
|
|
|
|
The output of length upto ``outlen'' is stored in ``out''. If ``outlen'' is initially larger than the size of the hash functions output
|
|
it is set to the number of bytes stored. If it is smaller than not all of the hash output is stored in ``out''.
|
|
|
|
\section{Algorithm Two}
|
|
|
|
Algorithm Two is the recommended algorithm for this task. It allows variable length salts and can produce outputs larger than the
|
|
hash functions output. As such it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required
|
|
from a single password and invokation of this algorithm.
|
|
|
|
\index{pkcs\_5\_alg2()}
|
|
\begin{alltt}
|
|
int pkcs_5_alg2(const unsigned char *password, unsigned long password_len,
|
|
const unsigned char *salt, unsigned long salt_len,
|
|
int iteration_count, int hash_idx,
|
|
unsigned char *out, unsigned long *outlen)
|
|
\end{alltt}
|
|
Where ``password'' is the users password. Since the algorithm allows binary passwords you must also specify the length in ``password\_len''.
|
|
The ``salt'' is an array of size ``salt\_len''. It should be random for each user and session. The ``iteration\_count'' is the delay desired
|
|
on the password. The ``hash\_idx'' is the index of the hash you wish to use in the descriptor table. The output of length upto
|
|
``outlen'' is stored in ``out''.
|
|
|
|
\begin{alltt}
|
|
/* demo to show how to make session state material from a password */
|
|
#include <mycrypt.h>
|
|
int main(void)
|
|
\{
|
|
unsigned char password[100], salt[100],
|
|
cipher_key[16], cipher_iv[16],
|
|
mac_key[16], outbuf[48];
|
|
int err, hash_idx;
|
|
unsigned long outlen, password_len, salt_len;
|
|
|
|
/* register hash and get it's idx .... */
|
|
|
|
/* get users password and make up a salt ... */
|
|
|
|
/* create the material (100 iterations in algorithm) */
|
|
outlen = sizeof(outbuf);
|
|
if ((err = pkcs_5_alg2(password, password_len, salt, salt_len,
|
|
100, hash_idx, outbuf, &outlen)) != CRYPT_OK) \{
|
|
/* error handle */
|
|
\}
|
|
|
|
/* now extract it */
|
|
memcpy(cipher_key, outbuf, 16);
|
|
memcpy(cipher_iv, outbuf+16, 16);
|
|
memcpy(mac_key, outbuf+32, 16);
|
|
|
|
/* use material (recall to store the salt in the output) */
|
|
\}
|
|
\end{alltt}
|
|
|
|
\chapter{Diffie-Hellman Key Exchange}
|
|
|
|
\section{Background}
|
|
|
|
Diffie-Hellman was the original public key system proposed. The system is based upon the group structure
|
|
of finite fields. For Diffie-Hellman a prime $p$ is chosen and a ``base'' $b$ such that $b^x\mbox{ }(\mbox{mod }p)$
|
|
generates a large sub-group of prime order (for unique values of $x$).
|
|
|
|
A secret key is an exponent $x$ and a public key is the value of $y \equiv g^x\mbox{ }(\mbox{mod }p)$. The term
|
|
``discrete logarithm'' denotes the action of finding $x$ given only $y$, $g$ and $p$. The key exchange part of
|
|
Diffie-Hellman arises from the fact that two users A and B with keys $(A_x, A_y)$ and $(B_x, B_y)$ can exchange
|
|
a shared key $K \equiv B_y^{A_x} \equiv A_y^{B_x} \equiv g^{A_xB_x}\mbox{ }(\mbox{mod }p)$.
|
|
|
|
From this public encryption and signatures can be developed. The trivial way to encrypt (for example) using a public key
|
|
$y$ is to perform the key exchange offline. The sender invents a key $k$ and its public copy
|
|
$k' \equiv g^k\mbox{ }(\mbox{mod }p)$ and uses $K \equiv k'^{A_x}\mbox{ }(\mbox{mod }p)$ as a key to encrypt
|
|
the message with. Typically $K$ would be sent to a one-way hash and the message digested used as a key in a
|
|
symmetric cipher.
|
|
|
|
It is important that the order of the sub-group that $g$ generates not only be large but also prime. There are
|
|
discrete logarithm algorithms that take $\sqrt r$ time given the order $r$. The discrete logarithm can be computed
|
|
modulo each prime factor of $r$ and the results combined using the Chinese Remainder Theorem. In the cases where
|
|
$r$ is ``B-Smooth'' (e.g. all small factors or powers of small prime factors) the solution is trivial to find.
|
|
|
|
To thwart such attacks the primes and bases in the library have been designed and fixed. Given a prime $p$ the order of
|
|
the sub-group generated is a large prime namely ${p - 1} \over 2$. Such primes are known as ``strong primes'' and the
|
|
smaller prime (e.g. the order of the base) are known as Sophie-Germaine primes.
|
|
|
|
\section{Core Functions}
|
|
|
|
This library also provides core Diffie-Hellman functions so you can negotiate keys over insecure mediums. The routines
|
|
provided are relatively easy to use and only take two function calls to negotiate a shared key. There is a structure
|
|
called ``dh\_key'' which stores the Diffie-Hellman key in a format these routines can use. The first routine is to
|
|
make a Diffie-Hellman private key pair:
|
|
\index{dh\_make\_key()}
|
|
\begin{verbatim}
|
|
int dh_make_key(prng_state *prng, int wprng,
|
|
int keysize, dh_key *key);
|
|
\end{verbatim}
|
|
The ``keysize'' is the size of the modulus you want in bytes. Currently support sizes are 96 to 512 bytes which correspond
|
|
to key sizes of 768 to 4096 bits. The smaller the key the faster it is to use however it will be less secure. When
|
|
specifying a size not explicitly supported by the library it will round {\em up} to the next key size. If the size is
|
|
above 512 it will return an error. So if you pass ``keysize == 32'' it will use a 768 bit key but if you pass
|
|
``keysize == 20000'' it will return an error. The primes and generators used are built-into the library and were designed
|
|
to meet very specific goals. The primes are strong primes which means that if $p$ is the prime then
|
|
$p-1$ is equal to $2r$ where $r$ is a large prime. The bases are chosen to generate a group of order $r$ to prevent
|
|
leaking a bit of the key. This means the bases generate a very large prime order group which is good to make cryptanalysis
|
|
hard.
|
|
|
|
The next two routines are for exporting/importing Diffie-Hellman keys in a binary format. This is useful for transport
|
|
over communication mediums.
|
|
|
|
\index{dh\_export()} \index{dh\_import()}
|
|
\begin{verbatim}
|
|
int dh_export(unsigned char *out, unsigned long *outlen,
|
|
int type, dh_key *key);
|
|
|
|
int dh_import(const unsigned char *in, unsigned long inlen, dh_key *key);
|
|
\end{verbatim}
|
|
|
|
These two functions work just like the ``rsa\_export()'' and ``rsa\_import()'' functions except these work with
|
|
Diffie-Hellman keys. Its important to note you do not have to free the ram for a ``dh\_key'' if an import fails. You can free a
|
|
``dh\_key'' using:
|
|
\begin{verbatim}
|
|
void dh_free(dh_key *key);
|
|
\end{verbatim}
|
|
After you have exported a copy of your public key (using {\bf PK\_PUBLIC} as ``type'') you can now create a shared secret
|
|
with the other user using:
|
|
\index{dh\_shared\_secret()}
|
|
\begin{verbatim}
|
|
int dh_shared_secret(dh_key *private_key,
|
|
dh_key *public_key,
|
|
unsigned char *out, unsigned long *outlen);
|
|
\end{verbatim}
|
|
|
|
Where ``private\_key'' is the key you made and ``public\_key'' is the copy of the public key the other user sent you. The result goes
|
|
into ``out'' and the length into ``outlen''. If all went correctly the data in ``out'' should be identical for both parties. It is important to
|
|
note that the two keys have to be the same size in order for this to work. There is a function to get the size of a
|
|
key:
|
|
\index{dh\_get\_size()}
|
|
\begin{verbatim}
|
|
int dh_get_size(dh_key *key);
|
|
\end{verbatim}
|
|
This returns the size in bytes of the modulus chosen for that key.
|
|
|
|
\subsection{Remarks on Usage}
|
|
Its important that you hash the shared key before trying to use it as a key for a symmetric cipher or something. An
|
|
example program that communicates over sockets, using MD5 and 1024-bit DH keys is\footnote{This function is a small example. It is suggested that proper packaging be used. For example, if the public key sent is truncated these routines will not detect that.}:
|
|
\newpage
|
|
\begin{small}
|
|
\begin{verbatim}
|
|
int establish_secure_socket(int sock, int mode, unsigned char *key,
|
|
prng_state *prng, int wprng)
|
|
{
|
|
unsigned char buf[4096], buf2[4096];
|
|
unsigned long x, len;
|
|
int res, err, inlen;
|
|
dh_key mykey, theirkey;
|
|
|
|
/* make up our private key */
|
|
if ((err = dh_make_key(prng, wprng, 128, &mykey)) != CRYPT_OK) {
|
|
return err;
|
|
}
|
|
|
|
/* export our key as public */
|
|
x = sizeof(buf);
|
|
if ((err = dh_export(buf, &x, PK_PUBLIC, &mykey)) != CRYPT_OK) {
|
|
res = err;
|
|
goto done2;
|
|
}
|
|
|
|
if (mode == 0) {
|
|
/* mode 0 so we send first */
|
|
if (send(sock, buf, x, 0) != x) {
|
|
res = CRYPT_ERROR;
|
|
goto done2;
|
|
}
|
|
|
|
/* get their key */
|
|
if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) {
|
|
res = CRYPT_ERROR;
|
|
goto done2;
|
|
}
|
|
} else {
|
|
/* mode >0 so we send second */
|
|
if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) {
|
|
res = CRYPT_ERROR;
|
|
goto done2;
|
|
}
|
|
|
|
if (send(sock, buf, x, 0) != x) {
|
|
res = CRYPT_ERROR;
|
|
goto done2;
|
|
}
|
|
}
|
|
|
|
if ((err = dh_import(buf2, inlen, &theirkey)) != CRYPT_OK) {
|
|
res = err;
|
|
goto done2;
|
|
}
|
|
|
|
/* make shared secret */
|
|
x = sizeof(buf);
|
|
if ((err = dh_shared_secret(&mykey, &theirkey, buf, &x)) != CRYPT_OK) {
|
|
res = err;
|
|
goto done;
|
|
}
|
|
|
|
/* hash it */
|
|
len = 16; /* default is MD5 so "key" must be at least 16 bytes long */
|
|
if ((err = hash_memory(find_hash("md5"), buf, x, key, &len)) != CRYPT_OK) {
|
|
res = err;
|
|
goto done;
|
|
}
|
|
|
|
/* clean up and return */
|
|
res = CRYPT_OK;
|
|
done:
|
|
dh_free(&theirkey);
|
|
done2:
|
|
dh_free(&mykey);
|
|
zeromem(buf, sizeof(buf));
|
|
zeromem(buf2, sizeof(buf2));
|
|
return res;
|
|
}
|
|
\end{verbatim}
|
|
\end{small}
|
|
\newpage
|
|
\subsection{Remarks on The Snippet}
|
|
When the above code snippet is done (assuming all went well) their will be a shared 128-bit key in the ``key'' array
|
|
passed to ``establish\_secure\_socket()''.
|
|
|
|
\section{Other Diffie-Hellman Functions}
|
|
In order to test the Diffie-Hellman function internal workings (e.g. the primes and bases) their is a test function made
|
|
available:
|
|
\index{dh\_test()}
|
|
\begin{verbatim}
|
|
int dh_test(void);
|
|
\end{verbatim}
|
|
|
|
This function returns {\bf CRYPT\_OK} if the bases and primes in the library are correct. There is one last helper
|
|
function:
|
|
\index{dh\_sizes()}
|
|
\begin{verbatim}
|
|
void dh_sizes(int *low, int *high);
|
|
\end{verbatim}
|
|
Which stores the smallest and largest key sizes support into the two variables.
|
|
|
|
\section{DH Packet}
|
|
Similar to the RSA related functions there are functions to encrypt or decrypt symmetric keys using the DH public key
|
|
algorithms.
|
|
\index{dh\_encrypt\_key()} \index{dh\_decrypt\_key()}
|
|
\begin{verbatim}
|
|
int dh_encrypt_key(const unsigned char *inkey, unsigned long keylen,
|
|
unsigned char *out, unsigned long *len,
|
|
prng_state *prng, int wprng, int hash,
|
|
dh_key *key);
|
|
|
|
int dh_decrypt_key(const unsigned char *in, unsigned long inlen,
|
|
unsigned char *outkey, unsigned long *keylen,
|
|
dh_key *key);
|
|
\end{verbatim}
|
|
Where ``inkey'' is an input symmetric key of no more than 32 bytes. Essentially these routines created a random public key
|
|
and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the
|
|
required data is placed in ``out'' by ``dh\_encrypt\_key()''. The hash must produce a message digest at least as large
|
|
as the symmetric key you are trying to share.
|
|
|
|
Similar to the RSA system you can sign and verify a hash of a message.
|
|
\index{dh\_sign\_hash()} \index{dh\_verify\_hash()}
|
|
\begin{verbatim}
|
|
int dh_sign_hash(const unsigned char *in, unsigned long inlen,
|
|
unsigned char *out, unsigned long *outlen,
|
|
prng_state *prng, int wprng, dh_key *key);
|
|
|
|
int dh_verify_hash(const unsigned char *sig, unsigned long siglen,
|
|
const unsigned char *hash, unsigned long hashlen,
|
|
int *stat, dh_key *key);
|
|
\end{verbatim}
|
|
|
|
The ``dh\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a DH packet in ``out''.
|
|
The ``dh\_verify\_hash'' function verifies the DH signature in ``sig'' against the hash in ``hash''. It sets ``stat''
|
|
to non-zero if the signature passes or zero if it fails.
|
|
|
|
\chapter{Elliptic Curve Cryptography}
|
|
|
|
\section{Background}
|
|
The library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the
|
|
Diffie-Hellman routines in the previous chapter. Elliptic curves (of certain forms) have the benefit that they are harder
|
|
to attack (no sub-exponential attacks exist unlike normal DH crypto) in fact the fastest attack requires the square root
|
|
of the order of the base point in time. That means if you use a base point of order $2^{192}$ (which would represent a
|
|
192-bit key) then the work factor is $2^{96}$ in order to find the secret key.
|
|
|
|
The curves in this library are taken from the following website:
|
|
\begin{verbatim}
|
|
http://csrc.nist.gov/cryptval/dss.htm
|
|
\end{verbatim}
|
|
|
|
They are all curves over the integers modulo a prime. The curves have the basic equation that is:
|
|
\begin{equation}
|
|
y^2 = x^3 - 3x + b\mbox{ }(\mbox{mod }p)
|
|
\end{equation}
|
|
|
|
The variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$
|
|
provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves
|
|
range in order from $\approx 2^{192}$ points to $\approx 2^{521}$. According to the source document any key size greater
|
|
than or equal to 256-bits is sufficient for long term security.
|
|
|
|
\section{Core Functions}
|
|
|
|
Like the DH routines there is a key structure ``ecc\_key'' used by the functions. There is a function to make a key:
|
|
\index{ecc\_make\_key()}
|
|
\begin{verbatim}
|
|
int ecc_make_key(prng_state *prng, int wprng,
|
|
int keysize, ecc_key *key);
|
|
\end{verbatim}
|
|
|
|
The ``keysize'' is the size of the modulus in bytes desired. Currently directly supported values are 20, 24, 28, 32, 48 and 65 bytes which
|
|
correspond to key sizes of 160, 192, 224, 256, 384 and 521 bits respectively. If you pass a key size that is between any key size
|
|
it will round the keysize up to the next available one. The rest of the parameters work like they do in the ``dh\_make\_key()'' function.
|
|
To free the ram allocated by a key call:
|
|
\index{ecc\_free()}
|
|
\begin{verbatim}
|
|
void ecc_free(ecc_key *key);
|
|
\end{verbatim}
|
|
|
|
To import and export a key there are:
|
|
\index{ecc\_export()}
|
|
\index{ecc\_import()}
|
|
\begin{verbatim}
|
|
int ecc_export(unsigned char *out, unsigned long *outlen,
|
|
int type, ecc_key *key);
|
|
|
|
int ecc_import(const unsigned char *in, unsigned long inlen, ecc_key *key);
|
|
\end{verbatim}
|
|
These two work exactly like there DH counterparts. Finally when you share your public key you can make a shared secret
|
|
with:
|
|
\index{ecc\_shared\_secret()}
|
|
\begin{verbatim}
|
|
int ecc_shared_secret(ecc_key *private_key,
|
|
ecc_key *public_key,
|
|
unsigned char *out, unsigned long *outlen);
|
|
\end{verbatim}
|
|
Which works exactly like the DH counterpart, the ``private\_key'' is your own key and ``public\_key'' is the key the other
|
|
user sent you. Note that this function stores both $x$ and $y$ co-ordinates of the shared
|
|
elliptic point. You should hash the output to get a shared key in a more compact and useful form (most of the entropy is
|
|
in $x$ anyways). Both keys have to be the same size for this to work, to help there is a function to get the size in bytes
|
|
of a key.
|
|
\index{ecc\_get\_size()}
|
|
\begin{verbatim}
|
|
int ecc_get_size(ecc_key *key);
|
|
\end{verbatim}
|
|
|
|
To test the ECC routines and to get the minimum and maximum key sizes there are these two functions:
|
|
\index{ecc\_test()}
|
|
\begin{verbatim}
|
|
int ecc_test(void);
|
|
void ecc_sizes(int *low, int *high);
|
|
\end{verbatim}
|
|
Which both work like their DH counterparts.
|
|
|
|
\section{ECC Packet}
|
|
Similar to the RSA API there are two functions which encrypt and decrypt symmetric keys using the ECC public key
|
|
algorithms.
|
|
|
|
\index{ecc\_encrypt\_key()} \index{ecc\_decrypt\_key()}
|
|
\begin{verbatim}
|
|
int ecc_encrypt_key(const unsigned char *inkey, unsigned long keylen,
|
|
unsigned char *out, unsigned long *len,
|
|
prng_state *prng, int wprng, int hash,
|
|
ecc_key *key);
|
|
|
|
int ecc_decrypt_key(const unsigned char *in, unsigned long inlen,
|
|
unsigned char *outkey, unsigned long *keylen,
|
|
ecc_key *key);
|
|
\end{verbatim}
|
|
|
|
Where ``inkey'' is an input symmetric key of no more than 32 bytes. Essentially these routines created a random public key
|
|
and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the required
|
|
data is placed in ``out'' by ``ecc\_encrypt\_key()''. The hash chosen must produce a message digest at least as large
|
|
as the symmetric key you are trying to share.
|
|
|
|
There are also functions to sign and verify the hash of a message.
|
|
\index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()}
|
|
\begin{verbatim}
|
|
int ecc_sign_hash(const unsigned char *in, unsigned long inlen,
|
|
unsigned char *out, unsigned long *outlen,
|
|
prng_state *prng, int wprng, ecc_key *key);
|
|
|
|
int ecc_verify_hash(const unsigned char *sig, unsigned long siglen,
|
|
const unsigned char *hash, unsigned long hashlen,
|
|
int *stat, ecc_key *key);
|
|
\end{verbatim}
|
|
|
|
The ``ecc\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a ECC packet in ``out''.
|
|
The ``ecc\_verify\_hash'' function verifies the ECC signature in ``sig'' against the hash in ``hash''. It sets ``stat''
|
|
to non-zero if the signature passes or zero if it fails.
|
|
|
|
|
|
\section{ECC Keysizes}
|
|
With ECC if you try and sign a hash that is bigger than your ECC key you can run into problems. The math will still work
|
|
and in effect the signature will still work. With ECC keys the strength of the signature is limited by the size of
|
|
the hash or the size of they key, whichever is smaller. For example, if you sign with SHA256 and a ECC-160 key in effect
|
|
you have 160-bits of security (e.g. as if you signed with SHA-1).
|
|
|
|
The library will not warn you if you make this mistake so it is important to check yourself before using the
|
|
signatures.
|
|
|
|
\chapter{Digital Signature Algorithm}
|
|
\section{Introduction}
|
|
The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to
|
|
reduce the bandwidth of a signature. For example, to have ``80-bits of security'' with ElGamal you need a group of
|
|
order at least 1024-bits. With DSA you need a group of order at least 160-bits. By comparison the ElGamal signature
|
|
would require at least 256 bytes where as the DSA signature would require only at least 40 bytes.
|
|
|
|
The API for the DSA is essentially the same as the other PK algorithms. Except in the case of DSA no encryption or
|
|
decryption routines are provided.
|
|
|
|
\section{Key Generation}
|
|
To make a DSA key you must call the following function
|
|
\begin{verbatim}
|
|
int dsa_make_key(prng_state *prng, int wprng,
|
|
int group_size, int modulus_size,
|
|
dsa_key *key);
|
|
\end{verbatim}
|
|
The variable ``prng'' is an active PRNG state and ``wprng'' the index to the descriptor. ``group\_size'' and
|
|
``modulus\_size'' control the difficulty of forging a signature. Both parameters are in bytes. The larger the
|
|
``group\_size'' the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by
|
|
$15 < group\_size < 1024$ and $modulus\_size - group\_size < 512$. Suggested values for the pairs are as follows.
|
|
|
|
\begin{center}
|
|
\begin{tabular}{|c|c|c|}
|
|
\hline \textbf{Bits of Security} & \textbf{group\_size} & \textbf{modulus\_size} \\
|
|
\hline 80 & 20 & 128 \\
|
|
\hline 120 & 30 & 256 \\
|
|
\hline 140 & 35 & 384 \\
|
|
\hline 160 & 40 & 512 \\
|
|
\hline
|
|
\end{tabular}
|
|
\end{center}
|
|
|
|
When you are finished with a DSA key you can call the following function to free the memory used.
|
|
\index{dsa\_free()}
|
|
\begin{verbatim}
|
|
void dsa_free(dsa_key *key);
|
|
\end{verbatim}
|
|
|
|
\section{Key Verification}
|
|
Each DSA key is composed of the following variables.
|
|
|
|
\begin{enumerate}
|
|
\item $q$ a small prime of magnitude $256^{group\_size}$.
|
|
\item $p = qr + 1$ a large prime of magnitude $256^{modulus\_size}$ where $r$ is a random even integer.
|
|
\item $g = h^r \mbox{ (mod }p\mbox{)}$ a generator of order $q$ modulo $p$. $h$ can be any non-trivial random
|
|
value. For this library they start at $h = 2$ and step until $g$ is not $1$.
|
|
\item $x$ a random secret (the secret key) in the range $1 < x < q$
|
|
\item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key.
|
|
\end{enumerate}
|
|
|
|
A DSA key is considered valid if it passes all of the following tests.
|
|
|
|
\begin{enumerate}
|
|
\item $q$ must be prime.
|
|
\item $p$ must be prime.
|
|
\item $g$ cannot be one of $\lbrace -1, 0, 1 \rbrace$ (modulo $p$).
|
|
\item $g$ must be less than $p$.
|
|
\item $(p-1) \equiv 0 \mbox{ (mod }q\mbox{)}$.
|
|
\item $g^q \equiv 1 \mbox{ (mod }p\mbox{)}$.
|
|
\item $1 < y < p - 1$
|
|
\item $y^q \equiv 1 \mbox{ (mod }p\mbox{)}$.
|
|
\end{enumerate}
|
|
|
|
Tests one and two ensure that the values will at least form a field which is required for the signatures to
|
|
function. Tests three and four ensure that the generator $g$ is not set to a trivial value which would make signature
|
|
forgery easier. Test five ensures that $q$ divides the order of multiplicative sub-group of $\Z/p\Z$. Test six
|
|
ensures that the generator actually generates a prime order group. Tests seven and eight ensure that the public key
|
|
is within range and belongs to a group of prime order. Note that test eight does not prove that $g$ generated $y$ only
|
|
that $y$ belongs to a multiplicative sub-group of order $q$.
|
|
|
|
The following function will perform these tests.
|
|
|
|
\index{dsa\_verify\_key()}
|
|
\begin{verbatim}
|
|
int dsa_verify_key(dsa_key *key, int *stat);
|
|
\end{verbatim}
|
|
|
|
This will test ``key'' and store the result in ``stat''. If the result is $stat = 0$ the DSA key failed one of the tests
|
|
and should not be used at all. If the result is $stat = 1$ the DSA key is valid (as far as valid mathematics are concerned).
|
|
|
|
|
|
|
|
\section{Signatures}
|
|
To generate a DSA signature call the following function
|
|
|
|
\index{dsa\_sign\_hash()}
|
|
\begin{verbatim}
|
|
int dsa_sign_hash(const unsigned char *in, unsigned long inlen,
|
|
unsigned char *out, unsigned long *outlen,
|
|
prng_state *prng, int wprng, dsa_key *key);
|
|
\end{verbatim}
|
|
|
|
Which will sign the data in ``in'' of length ``inlen'' bytes. The signature is stored in ``out'' and the size
|
|
of the signature in ``outlen''. If the signature is longer than the size you initially specify in ``outlen'' nothing
|
|
is stored and the function returns an error code. The DSA ``key'' must be of the \textbf{PK\_PRIVATE} persuasion.
|
|
|
|
To verify a hash created with that function use the following function
|
|
|
|
\index{dsa\_verify\_hash()}
|
|
\begin{verbatim}
|
|
int dsa_verify_hash(const unsigned char *sig, unsigned long siglen,
|
|
const unsigned char *hash, unsigned long inlen,
|
|
int *stat, dsa_key *key);
|
|
\end{verbatim}
|
|
Which will verify the data in ``hash'' of length ``inlen'' against the signature stored in ``sig'' of length ``siglen''.
|
|
It will set ``stat'' to $1$ if the signature is valid, otherwise it sets ``stat'' to $0$.
|
|
|
|
\section{Import and Export}
|
|
|
|
To export a DSA key so that it can be transported use the following function
|
|
\index{dsa\_export()}
|
|
\begin{verbatim}
|
|
int dsa_export(unsigned char *out, unsigned long *outlen,
|
|
int type,
|
|
dsa_key *key);
|
|
\end{verbatim}
|
|
This will export the DSA ``key'' to the buffer ``out'' and set the length in ``outlen'' (which must have been previously
|
|
initialized to the maximum buffer size). The ``type`` variable may be either \textbf{PK\_PRIVATE} or \textbf{PK\_PUBLIC}
|
|
depending on whether you want to export a private or public copy of the DSA key.
|
|
|
|
To import an exported DSA key use the following function
|
|
|
|
\index{dsa\_import()}
|
|
\begin{verbatim}
|
|
int dsa_import(const unsigned char *in, unsigned long inlen,
|
|
dsa_key *key);
|
|
\end{verbatim}
|
|
|
|
This will import the DSA key from the buffer ``in'' of length ``inlen'' to the ``key''. If the process fails the function
|
|
will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()).
|
|
|
|
\chapter{Miscellaneous}
|
|
\section{Base64 Encoding and Decoding}
|
|
The library provides functions to encode and decode a RFC1521 base64 coding scheme. This means that it can decode what it
|
|
encodes but the format used does not comply to any known standard. The characters used in the mappings are:
|
|
\begin{verbatim}
|
|
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
|
|
\end{verbatim}
|
|
Those characters should are supported in virtually any 7-bit ASCII system which means they can be used for transport over
|
|
common e-mail, usenet and HTTP mediums. The format of an encoded stream is just a literal sequence of ASCII characters
|
|
where a group of four represent 24-bits of input. The first four chars of the encoders output is the length of the
|
|
original input. After the first four characters is the rest of the message.
|
|
|
|
Often it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting. The decoder allows you to
|
|
put any character (that is not in the above sequence) in between any character of the encoders output. You may not however,
|
|
break up the first four characters.
|
|
|
|
To encode a binary string in base64 call:
|
|
\index{base64\_encode()} \index{base64\_decode()}
|
|
\begin{verbatim}
|
|
int base64_encode(const unsigned char *in, unsigned long len,
|
|
unsigned char *out, unsigned long *outlen);
|
|
\end{verbatim}
|
|
Where ``in'' is the binary string and ``out'' is where the ASCII output is placed. You must set the value of ``outlen'' prior
|
|
to calling this function and it sets the length of the base64 output in ``outlen'' when it is done. To decode a base64
|
|
string call:
|
|
\begin{verbatim}
|
|
int base64_decode(const unsigned char *in, unsigned long len,
|
|
unsigned char *out, unsigned long *outlen);
|
|
\end{verbatim}
|
|
|
|
\section{The Multiple Precision Integer Library (MPI)}
|
|
The library comes with a copy of LibTomMath which is a multiple precision integer library written by the
|
|
author of LibTomCrypt. LibTomMath is a trivial to use ANSI C compatible large integer library which is free
|
|
for all uses and is distributed freely.
|
|
|
|
At the heart of all the functions is the data type ``mp\_int'' (defined in tommath.h). This data type is what
|
|
will hold all large integers. In order to use an mp\_int one must initialize it first, for example:
|
|
\begin{verbatim}
|
|
#include <mycrypt.h> /* mycrypt.h includes mpi.h automatically */
|
|
int main(void)
|
|
{
|
|
mp_int bignum;
|
|
|
|
/* initialize it */
|
|
mp_init(&bignum);
|
|
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
If you are unfamiliar with the syntax of C the \& symbol is used to pass the address of ``bignum'' to the function. All
|
|
LibTomMath functions require the address of the parameters. To free the memory of a mp\_int use (for example):
|
|
\begin{verbatim}
|
|
mp_clear(&bignum);
|
|
\end{verbatim}
|
|
|
|
The functions also have the basic form of one of the following:
|
|
\begin{verbatim}
|
|
mp_XXX(mp_int *a);
|
|
mp_XXX(mp_int *a, mp_int *b, mp_int *c);
|
|
mp_XXX(mp_int *a, mp_int *b, mp_int *c, mp_int *d);
|
|
\end{verbatim}
|
|
|
|
Where they perform some operation and store the result in the mp\_int variable passed on the far right.
|
|
For example, to compute $c = a + b \mbox{ }(\mbox{mod }m)$ you would call:
|
|
\begin{verbatim}
|
|
mp_addmod(&a, &b, &m, &c);
|
|
\end{verbatim}
|
|
|
|
\subsection{Binary Forms of ``mp\_int'' Variables}
|
|
|
|
Often it is required to store a ``mp\_int'' in binary form for transport (e.g. exporting a key, packet
|
|
encryption, etc.). LibTomMath includes two functions to help when exporting numbers:
|
|
\begin{verbatim}
|
|
int mp_raw_size(mp_int *num);
|
|
mp_toraw(&num, buf);
|
|
\end{verbatim}
|
|
|
|
The former function gives the size in bytes of the raw format and the latter function actually stores the raw data. All
|
|
``mp\_int'' numbers are stored in big endian form (like PKCS demands) with the first byte being the sign of the number. The
|
|
``rsa\_exptmod()'' function differs slightly since it will take the input in the form exactly as PKCS demands (without the
|
|
leading sign byte). All other functions include the sign byte (since its much simpler just to include it). The sign byte
|
|
must be zero for positive numbers and non-zero for negative numbers. For example,
|
|
the sequence:
|
|
\begin{verbatim}
|
|
00 FF 30 04
|
|
\end{verbatim}
|
|
Represents the integer $255 \cdot 256^2 + 48 \cdot 256^1 + 4 \cdot 256^0$ or 16,723,972.
|
|
|
|
To read a binary string back into a ``mp\_int'' call:
|
|
\begin{verbatim}
|
|
mp_read_raw(mp_int *num, unsigned char *str, int len);
|
|
\end{verbatim}
|
|
Where ``num'' is where to store it, ``str'' is the binary string (including the leading sign byte) and ``len'' is the
|
|
length of the binary string.
|
|
|
|
\subsection{Primality Testing}
|
|
\index{Primality Testing}
|
|
The library includes primality testing and random prime functions as well. The primality tester will perform the test in
|
|
two phases. First it will perform trial division by the first few primes. Second it will perform eight rounds of the
|
|
Rabin-Miller primality testing algorithm. If the candidate passes both phases it is declared prime otherwise it is declared
|
|
composite. No prime number will fail the two phases but composites can. Each round of the Rabin-Miller algorithm reduces
|
|
the probability of a pseudo-prime by $1 \over 4$ therefore after sixteen rounds the probability is no more than
|
|
$\left ( { 1 \over 4 } \right )^{8} = 2^{-16}$. In practice the probability of error is in fact much lower than that.
|
|
|
|
When making random primes the trial division step is in fact an optimized implementation of ``Implementation of Fast RSA Key Generation on Smart Cards''\footnote{Chenghuai Lu, Andre L. M. dos Santos and Francisco R. Pimentel}.
|
|
In essence a table of machine-word sized residues are kept of a candidate modulo a set of primes. When the candiate
|
|
is rejected and ultimately incremented to test the next number the residues are updated without using multi-word precision
|
|
math operations. As a result the routine can scan ahead to the next number required for testing with very little work
|
|
involved.
|
|
|
|
In the event that a composite did make it through it would most likely cause the the algorithm trying to use it to fail. For
|
|
instance, in RSA two primes $p$ and $q$ are required. The order of the multiplicative sub-group (modulo $pq$) is given
|
|
as $\phi(pq)$ or $(p - 1)(q - 1)$. The decryption exponent $d$ is found as $de \equiv 1\mbox{ }(\mbox{mod } \phi(pq))$. If either $p$ or $q$ is composite the value of $d$ will be incorrect and the user
|
|
will not be able to sign or decrypt messages at all. Suppose $p$ was prime and $q$ was composite this is just a variation of
|
|
the multi-prime RSA. Suppose $q = rs$ for two primes $r$ and $s$ then $\phi(pq) = (p - 1)(r - 1)(s - 1)$ which clearly is
|
|
not equal to $(p - 1)(rs - 1)$.
|
|
|
|
These are not technically part of the LibTomMath library but this is the best place to document them.
|
|
To test if a ``mp\_int'' is prime call:
|
|
\begin{verbatim}
|
|
int is_prime(mp_int *N, int *result);
|
|
\end{verbatim}
|
|
This puts a one in ``result'' if the number is probably prime, otherwise it places a zero in it. It is assumed that if
|
|
it returns an error that the value in ``result'' is undefined. To make
|
|
a random prime call:
|
|
\begin{verbatim}
|
|
int rand_prime(mp_int *N, unsigned long len, prng_state *prng, int wprng);
|
|
\end{verbatim}
|
|
Where ``len'' is the size of the prime in bytes ($2 \le len \le 256$). You can set ``len'' to the negative size you want
|
|
to get a prime of the form $p \equiv 3\mbox{ }(\mbox{mod } 4)$. So if you want a 1024-bit prime of this sort pass
|
|
``len = -128'' to the function. Upon success it will return {\bf CRYPT\_OK} and ``N'' will contain an integer which
|
|
is very likely prime.
|
|
|
|
\chapter{Programming Guidelines}
|
|
|
|
\section{Secure Pseudo Random Number Generators}
|
|
Probably the singal most vulnerable point of any cryptosystem is the PRNG. Without one generating and protecting secrets
|
|
would be impossible. The requirement that one be setup correctly is vitally important and to address this point the library
|
|
does provide two RNG sources that will address the largest amount of end users as possible. The ``sprng'' PRNG provided
|
|
provides and easy to access source of entropy for any application on a *NIX or Windows computer.
|
|
|
|
However, when the end user is not on one of these platforms the application developer must address the issue of finding
|
|
entropy. This manual is not designed to be a text on cryptography. I would just like to highlight that when you design
|
|
a cryptosystem make sure the first problem you solve is getting a fresh source of entropy.
|
|
|
|
\section{Preventing Trivial Errors}
|
|
Two simple ways to prevent trivial errors is to prevent overflows and to check the return values. All of the functions
|
|
which output variable length strings will require you to pass the length of the destination. If the size of your output
|
|
buffer is smaller than the output it will report an error. Therefore, make sure the size you pass is correct!
|
|
|
|
Also virtually all of the functions return an error code or {\bf CRYPT\_OK}. You should detect all errors as simple
|
|
typos or such can cause algorithms to fail to work as desired.
|
|
|
|
\section{Registering Your Algorithms}
|
|
To avoid linking and other runtime errors it is important to register the ciphers, hashes and PRNGs you intend to use
|
|
before you try to use them. This includes any function which would use an algorithm indirectly through a descriptor table.
|
|
|
|
A neat bonus to the registry system is that you can add external algorithms that are not part of the library without
|
|
having to hack the library. For example, suppose you have a hardware specific PRNG on your system. You could easily
|
|
write the few functions required plus a descriptor. After registering your PRNG all of the library functions that
|
|
need a PRNG can instantly take advantage of it.
|
|
|
|
\section{Key Sizes}
|
|
|
|
\subsection{Symmetric Ciphers}
|
|
For symmetric ciphers use as large as of a key as possible. For the most part ``bits are cheap'' so using a 256-bit key
|
|
is not a hard thing todo.
|
|
|
|
\subsection{Assymetric Ciphers}
|
|
The following chart gives the work factor for solving a DH/RSA public key using the NFS. The work factor for a key of order
|
|
$n$ is estimated to be
|
|
\begin{equation}
|
|
e^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}}
|
|
\end{equation}
|
|
|
|
Note that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required
|
|
is:
|
|
\begin{center}
|
|
\begin{tabular}{|c|c|}
|
|
\hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\
|
|
\hline 512 & 63.92 \\
|
|
\hline 768 & 76.50 \\
|
|
\hline 1024 & 86.76 \\
|
|
\hline 1536 & 103.37 \\
|
|
\hline 2048 & 116.88 \\
|
|
\hline 2560 & 128.47 \\
|
|
\hline 3072 & 138.73 \\
|
|
\hline 4096 & 156.49 \\
|
|
\hline
|
|
\end{tabular}
|
|
\end{center}
|
|
|
|
The work factor for ECC keys is much higher since the best attack is still fully exponentional. Given a key of magnitude
|
|
$n$ it requires $\sqrt n$ work. The following table sumarizes the work required:
|
|
\begin{center}
|
|
\begin{tabular}{|c|c|}
|
|
\hline ECC Key Size (bits) & Work Factor ($log_2$) \\
|
|
\hline 160 & 80 \\
|
|
\hline 192 & 96 \\
|
|
\hline 224 & 112 \\
|
|
\hline 256 & 128 \\
|
|
\hline 384 & 192 \\
|
|
\hline 521 & 260.5 \\
|
|
\hline
|
|
\end{tabular}
|
|
\end{center}
|
|
|
|
Using the above tables the following suggestions for key sizes seems appropriate:
|
|
\begin{center}
|
|
\begin{tabular}{|c|c|c|}
|
|
\hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\
|
|
\hline Short term (less than a year) & 1024 & 160 \\
|
|
\hline Short term (less than five years) & 1536 & 192 \\
|
|
\hline Long Term (less than ten years) & 2560 & 256 \\
|
|
\hline
|
|
\end{tabular}
|
|
\end{center}
|
|
|
|
\section{Thread Safety}
|
|
The library is not thread safe but several simple precautions can be taken to avoid any problems. The registry functions
|
|
such as register\_cipher() are not thread safe no matter what you do. Its best to call them from your programs initializtion
|
|
code before threads are initiated.
|
|
|
|
The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc. This means that if each
|
|
thread has its own state variables then they will not affect each other. This is fairly simple with symmetric ciphers
|
|
and hashes. However, the keyring and PRNG support is something the threads will want to share. The simplest workaround
|
|
is create semaphores or mutexes around calls to those functions.
|
|
|
|
Since C does not have standard semaphores this support is not native to Libtomcrypt. Even a C based semaphore is not entire
|
|
possible as some compilers may ignore the ``volatile'' keyword or have multiple processors. Provide your host application
|
|
is modular enough putting the locks in the right place should not bloat the code significantly and will solve all thread
|
|
safety issues within the library.
|
|
|
|
\chapter{Configuring the Library}
|
|
\section{Introduction}
|
|
The library is fairly flexible about how it can be built, used and generally distributed. Additions are being made with
|
|
each new release that will make the library even more flexible. Most options are placed in the makefile and others
|
|
are in ``mycrypt\_cfg.h''. All are used when the library is built from scratch.
|
|
|
|
For GCC platforms the file ``makefile'' is the makefile to be used. On MSVC platforms ``makefile.vc'' and on PS2 platforms
|
|
``makefile.ps2''.
|
|
|
|
\section{mycrypt\_cfg.h}
|
|
The file ``mycrypt\_cfg.h'' is what lets you control what functionality you want to remove from the library. By default,
|
|
everything the library has to offer it built.
|
|
|
|
\subsubsection{ARGTYPE}
|
|
This lets you control how the \_ARGCHK macro will behave. The macro is used to check pointers inside the functions against
|
|
NULL. There are three settings for ARGTYPE. When set to 0 it will have the default behaviour of printing a message to
|
|
stderr and raising a SIGABRT signal. This is provided so all platforms that use libtomcrypt can have an error that functions
|
|
similarly. When set to 1 it will simply pass on to the assert() macro. When set to 2 it will resolve to a empty macro
|
|
and no error checking will be performed.
|
|
|
|
\subsubsection{Endianess}
|
|
There are five macros related to endianess issues. For little endian platforms define, ENDIAN\_LITTLE. For big endian
|
|
platforms define ENDIAN\_BIG. Similarly when the default word size of an ``unsigned long'' is 32-bits define ENDIAN\_32BITWORD
|
|
or define ENDIAN\_64BITWORD when its 64-bits. If you do not define any of them the library will automatically use ENDIAN\_NEUTRAL
|
|
which will work on all platforms. Currently the system will automatically detect GCC or MSVC on a windows platform as well
|
|
as GCC on a PS2 platform.
|
|
|
|
\section{The Configure Script}
|
|
There are also options you can specify from the configure script or ``mycrypt\_config.h''.
|
|
|
|
\subsubsection{X memory routines}
|
|
The makefiles must define three macros denoted as XMALLOC, XCALLOC and XFREE which resolve to the name of the respective
|
|
functions. This lets you substitute in your own memory routines. If you substitute in your own functions they must behave
|
|
like the standard C library functions in terms of what they expect as input and output. By default the library uses the
|
|
standard C routines.
|
|
|
|
\subsubsection{X clock routines}
|
|
The rng\_get\_bytes() function can call a function that requires the clock() function. These macros let you override
|
|
the default clock() used with a replacement. By default the standard C library clock() function is used.
|
|
|
|
\subsubsection{NO\_FILE}
|
|
During the build if NO\_FILE is defined then any function in the library that uses file I/O will not call the file I/O
|
|
functions and instead simply return CRYPT\_ERROR. This should help resolve any linker errors stemming from a lack of
|
|
file I/O on embedded platforms.
|
|
|
|
\subsubsection{CLEAN\_STACK}
|
|
When this functions is defined the functions that store key material on the stack will clean up afterwards. Assumes that
|
|
you have no memory paging with the stack.
|
|
|
|
\subsubsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions}
|
|
There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly self-explanatory.
|
|
When they are defined the functionality is included otherwise it is not. There are some dependency issues which are
|
|
noted in the file. For instance, Yarrow requires CTR chaining mode, a block cipher and a hash function.
|
|
|
|
\subsubsection{TWOFISH\_SMALL and TWOFISH\_TABLES}
|
|
Twofish is a 128-bit symmetric block cipher that is provided within the library. The cipher itself is flexible enough
|
|
to allow some tradeoffs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish
|
|
requires only 200 bytes of memory. This is achieved by not pre-computing the substitution boxes. Having this
|
|
defined will also greatly slow down the cipher. When this macro is not defined Twofish will pre-compute the
|
|
tables at a cost of 4KB of memory. The cipher will be much faster as a result.
|
|
|
|
When TWOFISH\_TABLES is defined the cipher will use pre-computed (and fixed in code) tables required to work. This is
|
|
useful when TWOFISH\_SMALL is defined as the table values are computed on the fly. When this is defined the code size
|
|
will increase by approximately 500 bytes. If this is defined but TWOFISH\_SMALL is not the cipher will still work but
|
|
it will not speed up the encryption or decryption functions.
|
|
|
|
\subsubsection{SMALL\_CODE}
|
|
When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants.
|
|
These variants are slower but can save quite a bit of code space.
|
|
|
|
\input{crypt.ind}
|
|
|
|
\end{document}
|