|
3
|
1 \documentclass[b5paper]{book} |
|
|
2 \usepackage{hyperref} |
|
|
3 \usepackage{makeidx} |
|
|
4 \usepackage{amssymb} |
|
|
5 \usepackage{color} |
|
|
6 \usepackage{alltt} |
|
|
7 \usepackage{graphicx} |
|
|
8 \usepackage{layout} |
|
|
9 \def\union{\cup} |
|
|
10 \def\intersect{\cap} |
|
|
11 \def\getsrandom{\stackrel{\rm R}{\gets}} |
|
|
12 \def\cross{\times} |
|
|
13 \def\cat{\hspace{0.5em} \| \hspace{0.5em}} |
|
|
14 \def\catn{$\|$} |
|
|
15 \def\divides{\hspace{0.3em} | \hspace{0.3em}} |
|
|
16 \def\nequiv{\not\equiv} |
|
|
17 \def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}} |
|
|
18 \def\lcm{{\rm lcm}} |
|
|
19 \def\gcd{{\rm gcd}} |
|
|
20 \def\log{{\rm log}} |
|
|
21 \def\ord{{\rm ord}} |
|
|
22 \def\abs{{\mathit abs}} |
|
|
23 \def\rep{{\mathit rep}} |
|
|
24 \def\mod{{\mathit\ mod\ }} |
|
|
25 \renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})} |
|
|
26 \newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor} |
|
|
27 \newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil} |
|
|
28 \def\Or{{\rm\ or\ }} |
|
|
29 \def\And{{\rm\ and\ }} |
|
|
30 \def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}} |
|
|
31 \def\implies{\Rightarrow} |
|
|
32 \def\undefined{{\rm ``undefined"}} |
|
|
33 \def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}} |
|
|
34 \let\oldphi\phi |
|
|
35 \def\phi{\varphi} |
|
|
36 \def\Pr{{\rm Pr}} |
|
|
37 \newcommand{\str}[1]{{\mathbf{#1}}} |
|
|
38 \def\F{{\mathbb F}} |
|
|
39 \def\N{{\mathbb N}} |
|
|
40 \def\Z{{\mathbb Z}} |
|
|
41 \def\R{{\mathbb R}} |
|
|
42 \def\C{{\mathbb C}} |
|
|
43 \def\Q{{\mathbb Q}} |
|
|
44 |
|
|
45 \def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}} |
|
|
46 |
|
|
47 \def\gap{\vspace{0.5ex}} |
|
|
48 \makeindex |
|
|
49 \begin{document} |
|
15
|
50 \title{A Tiny Crypto Library, \\ LibTomCrypt \\ Version 0.96} |
|
3
|
51 \author{Tom St Denis \\ |
|
|
52 \\ |
|
|
53 [email protected] \\ |
|
|
54 http://libtomcrypt.org \\ \\ |
|
|
55 Phone: 1-613-836-3160\\ |
|
|
56 111 Banning Rd \\ |
|
|
57 Kanata, Ontario \\ |
|
|
58 K2L 1C3 \\ |
|
|
59 Canada |
|
|
60 } |
|
|
61 \maketitle |
|
|
62 This text and source code library are both hereby placed in the public domain. This book has been |
|
|
63 formatted for B5 [176x250] paper using the \LaTeX{} {\em book} macro package. |
|
|
64 |
|
|
65 \vspace{10cm} |
|
|
66 |
|
|
67 \begin{flushright}Open Source. Open Academia. Open Minds. |
|
|
68 |
|
|
69 \mbox{ } |
|
|
70 |
|
|
71 Tom St Denis, |
|
|
72 |
|
|
73 Ontario, Canada |
|
|
74 \end{flushright} |
|
|
75 \newpage |
|
|
76 \tableofcontents |
|
|
77 \chapter{Introduction} |
|
|
78 \section{What is the LibTomCrypt?} |
|
|
79 LibTomCrypt is a portable ANSI C cryptographic library that supports symmetric ciphers, one-way hashes, |
|
|
80 pseudo-random number generators, public key cryptography (via RSA,DH or ECC/DH) and a plethora of support |
|
|
81 routines. It is designed to compile out of the box with the GNU C Compiler (GCC) version 2.95.3 (and higher) |
|
|
82 and with MSVC version 6 in win32. |
|
|
83 |
|
|
84 The library has been successfully tested on quite a few other platforms ranging from the ARM7TDMI in a |
|
|
85 Gameboy Advanced to various PowerPC processors and even the MIPS processor in the PlayStation 2. Suffice it |
|
|
86 to say the code is portable. |
|
|
87 |
|
|
88 The library is designed so new ciphers/hashes/PRNGs can be added at runtime and the existing API (and helper API functions) will |
|
|
89 be able to use the new designs automatically. There exist self-check functions for each cipher and hash to ensure that |
|
|
90 they compile and execute to the published design specifications. The library also performs extensive parameter error checking |
|
|
91 and will give verbose error messages when possible. |
|
|
92 |
|
|
93 Essentially the library saves the time of having to implement the ciphers, hashes, prngs yourself. Typically implementing |
|
|
94 useful cryptography is an error prone business which means anything that can save considerable time and effort is a good |
|
|
95 thing. |
|
|
96 |
|
|
97 \subsection{What the library IS for?} |
|
|
98 |
|
|
99 The library typically serves as a basis for other protocols and message formats. For example, it should be possible to |
|
|
100 take the RSA routines out of this library, apply the appropriate message padding and get PKCS compliant RSA routines. |
|
|
101 Similarly SSL protocols could be formed on top of the low-level symmetric cipher functions. The goal of this package is |
|
|
102 to provide these low level core functions in a robust and easy to use fashion. |
|
|
103 |
|
|
104 The library also serves well as a toolkit for applications where they don't need to be OpenPGP, PKCS, etc. compliant. |
|
|
105 Included are fully operational public key routines for encryption, decryption, signature generation and verification. |
|
15
|
106 These routines are fully portable but are not conformant to any known set of standards\footnote{With the exception of |
|
|
107 the RSA code which is based on the PKCS \#1 standards.}. They are all based on established |
|
3
|
108 number theory and cryptography. |
|
|
109 |
|
|
110 \subsection{What the library IS NOT for?} |
|
|
111 |
|
|
112 The library is not designed to be in anyway an implementation of the SSL or OpenPGP standards. The library |
|
|
113 is not designed to be compliant with any known form of API or programming hierarchy. It is not a port of any other |
|
|
114 library and it is not platform specific (like the MS CSP). So if you're looking to drop in some buzzword |
|
|
115 compliant crypto library this is not for you. The library has been written from scratch to provide basic functions as |
|
|
116 well as non-standard higher level functions. |
|
|
117 |
|
|
118 This is not to say that the library is a ``homebrew'' project. All of the symmetric ciphers and one-way hash functions |
|
|
119 conform to published test vectors. The public key functions are derived from publicly available material and the majority |
|
|
120 of the code has been reviewed by a growing community of developers. |
|
|
121 |
|
|
122 \subsubsection{Why not?} |
|
|
123 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 |
|
|
124 is quite simple too much money gets in the way. When I tried to access the P1363 draft documents and was denied (it |
|
|
125 requires a password) I realized that they're just a business anyways. See what happens is a company will sit down and |
|
|
126 invent a ``standard''. Then they try to sell it to as many people as they can. All of a sudden this ``standard'' is |
|
|
127 everywhere. Then the standard is updated every so often to keep people dependent. Then you become RSA. If people are |
|
|
128 supposed to support these standards they had better make them more accessible. |
|
|
129 |
|
|
130 \section{Why did I write it?} |
|
|
131 You may be wondering, ``Tom, why did you write a crypto library. I already have one.''. Well the reason falls into |
|
|
132 two categories: |
|
|
133 \begin{enumerate} |
|
|
134 \item I am too lazy to figure out someone else's API. I'd rather invent my own simpler API and use that. |
|
|
135 \item It was (still is) good coding practice. |
|
|
136 \end{enumerate} |
|
|
137 |
|
|
138 The idea is that I am not striving to replace OpenSSL or Crypto++ or Cryptlib or etc. I'm trying to write my |
|
|
139 {\bf own} crypto library and hopefully along the way others will appreciate the work. |
|
|
140 |
|
|
141 With this library all core functions (ciphers, hashes, prngs) have the {\bf exact} same prototype definition. They all load |
|
|
142 and store data in a format independent of the platform. This means if you encrypt with Blowfish on a PPC it should decrypt |
|
|
143 on an x86 with zero problems. The consistent API also means that if you learn how to use blowfish with my library you |
|
|
144 know how to use Safer+ or RC6 or Serpent or ... as well. With all of the core functions there are central descriptor tables |
|
|
145 that can be used to make a program automatically pick between ciphers, hashes and PRNGs at runtime. That means your |
|
|
146 application can support all ciphers/hashes/prngs without changing the source code. |
|
|
147 |
|
|
148 \subsection{Modular} |
|
|
149 The LibTomCrypt package has also been written to be very modular. The block ciphers, one-way hashes and |
|
|
150 pseudo-random number generators (PRNG) are all used within the API through ``descriptor'' tables which |
|
|
151 are essentially structures with pointers to functions. While you can still call particular functions |
|
|
152 directly (\textit{e.g. sha256\_process()}) this descriptor interface allows the developer to customize their |
|
|
153 usage of the library. |
|
|
154 |
|
|
155 For example, consider a hardware platform with a specialized RNG device. Obviously one would like to tap |
|
|
156 that for the PRNG needs within the library (\textit{e.g. making a RSA key}). All the developer has todo |
|
|
157 is write a descriptor and the few support routines required for the device. After that the rest of the |
|
|
158 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 |
|
|
159 invented. It can be added to the library and used within applications with zero modifications to the |
|
|
160 end applications provided they are written properly. |
|
|
161 |
|
|
162 This flexibility within the library means it can be used with any combination of primitive algorithms and |
|
|
163 unlike libraries like OpenSSL is not tied to direct routines. For instance, in OpenSSL there are CBC block |
|
|
164 mode routines for every single cipher. That means every time you add or remove a cipher from the library |
|
|
165 you have to update the associated support code as well. In LibTomCrypt the associated code (\textit{chaining modes in this case}) |
|
|
166 are not directly tied to the ciphers. That is a new cipher can be added to the library by simply providing |
|
|
167 the key setup, ECB decrypt and encrypt and test vector routines. After that all five chaining mode routines |
|
|
168 can make use of the cipher right away. |
|
|
169 |
|
|
170 |
|
|
171 \section{License} |
|
|
172 |
|
|
173 All of the source code except for the following files have been written by the author or donated to the project |
|
|
174 under a public domain license: |
|
|
175 |
|
|
176 \begin{enumerate} |
|
|
177 \item rc2.c |
|
|
178 \item safer.c |
|
|
179 \end{enumerate} |
|
|
180 |
|
|
181 `mpi.c'' was originally written by Michael Fromberger ([email protected]) but has since been replaced with my LibTomMath |
|
|
182 library. |
|
|
183 |
|
|
184 ``rc2.c'' is based on publicly available code that is not attributed to a person from the given source. ``safer.c'' |
|
|
185 was written by Richard De Moliner ([email protected]) and is public domain. |
|
|
186 |
|
|
187 The project is hereby released as public domain. |
|
|
188 |
|
|
189 \section{Patent Disclosure} |
|
|
190 |
|
|
191 The author (Tom St Denis) is not a patent lawyer so this section is not to be treated as legal advice. To the best |
|
|
192 of the authors knowledge the only patent related issues within the library are the RC5 and RC6 symmetric block ciphers. |
|
|
193 They can be removed from a build by simply commenting out the two appropriate lines in the makefile script. The rest |
|
|
194 of the ciphers and hashes are patent free or under patents that have since expired. |
|
|
195 |
|
|
196 The RC2 and RC4 symmetric ciphers are not under patents but are under trademark regulations. This means you can use |
|
|
197 the ciphers you just can't advertise that you are doing so. |
|
|
198 |
|
|
199 \section{Building the library} |
|
|
200 |
|
|
201 To build the library on a GCC equipped platform simply type ``make'' at your command prompt. It will build the library |
|
|
202 file ``libtomcrypt.a''. |
|
|
203 |
|
|
204 To install the library copy all of the ``.h'' files into your ``\#include'' path and the single libtomcrypt.a file into |
|
|
205 your library path. |
|
|
206 |
|
|
207 With MSVC you can build the library with ``nmake -f makefile.msvc''. This will produce a ``tomcrypt.lib'' file which |
|
|
208 is the core library. Copy the header files into your MSVC include path and the library in the lib path (typically |
|
|
209 under where VC98 is installed). |
|
|
210 |
|
|
211 \section{Building against the library} |
|
|
212 |
|
|
213 In the recent versions the build steps have changed. The build options are now stored in ``mycrypt\_custom.h'' and |
|
|
214 no longer in the makefile. If you change a build option in that file you must re-build the library from clean to |
|
|
215 ensure the build is intact. The perl script ``config.pl'' will help setup the custom header and a custom makefile |
|
|
216 if you want one (the provided ``makefile'' will work with custom configs). |
|
|
217 |
|
|
218 \section{Thanks} |
|
|
219 I would like to give thanks to the following people (in no particular order) for helping me develop this project: |
|
|
220 \begin{enumerate} |
|
|
221 \item Richard van de Laarschot |
|
|
222 \item Richard Heathfield |
|
|
223 \item Ajay K. Agrawal |
|
|
224 \item Brian Gladman |
|
|
225 \item Svante Seleborg |
|
|
226 \item Clay Culver |
|
|
227 \item Jason Klapste |
|
|
228 \item Dobes Vandermeer |
|
|
229 \item Daniel Richards |
|
|
230 \item Wayne Scott |
|
|
231 \item Andrew Tyler |
|
|
232 \item Sky Schulz |
|
|
233 \item Christopher Imes |
|
|
234 \end{enumerate} |
|
|
235 |
|
|
236 \chapter{The Application Programming Interface (API)} |
|
|
237 \section{Introduction} |
|
|
238 \index{CRYPT\_ERROR} \index{CRYPT\_OK} |
|
|
239 |
|
|
240 In general the API is very simple to memorize and use. Most of the functions return either {\bf void} or {\bf int}. Functions |
|
|
241 that return {\bf int} will return {\bf CRYPT\_OK} if the function was successful or one of the many error codes |
|
|
242 if it failed. Certain functions that return int will return $-1$ to indicate an error. These functions will be explicitly |
|
|
243 commented upon. When a function does return a CRYPT error code it can be translated into a string with |
|
|
244 |
|
15
|
245 \index{error\_to\_string()} |
|
3
|
246 \begin{verbatim} |
|
15
|
247 const char *error_to_string(int err); |
|
3
|
248 \end{verbatim} |
|
|
249 |
|
|
250 An example of handling an error is: |
|
|
251 \begin{verbatim} |
|
|
252 void somefunc(void) |
|
|
253 { |
|
15
|
254 int err; |
|
3
|
255 |
|
|
256 /* call a cryptographic function */ |
|
15
|
257 if ((err = some_crypto_function(...)) != CRYPT_OK) { |
|
|
258 printf("A crypto error occured, %s\n", error_to_string(err)); |
|
3
|
259 /* perform error handling */ |
|
|
260 } |
|
|
261 /* continue on if no error occured */ |
|
|
262 } |
|
|
263 \end{verbatim} |
|
|
264 |
|
|
265 There is no initialization routine for the library and for the most part the code is thread safe. The only thread |
|
|
266 related issue is if you use the same symmetric cipher, hash or public key state data in multiple threads. Normally |
|
|
267 that is not an issue. |
|
|
268 |
|
|
269 To include the prototypes for ``LibTomCrypt.a'' into your own program simply include ``mycrypt.h'' like so: |
|
|
270 \begin{verbatim} |
|
|
271 #include <mycrypt.h> |
|
|
272 int main(void) { |
|
|
273 return 0; |
|
|
274 } |
|
|
275 \end{verbatim} |
|
|
276 |
|
|
277 The header file ``mycrypt.h'' also includes ``stdio.h'', ``string.h'', ``stdlib.h'', ``time.h'', ``ctype.h'' and ``mpi.h'' |
|
|
278 (the bignum library routines). |
|
|
279 |
|
|
280 \section{Macros} |
|
|
281 |
|
|
282 There are a few helper macros to make the coding process a bit easier. The first set are related to loading and storing |
|
|
283 32/64-bit words in little/big endian format. The macros are: |
|
|
284 |
|
|
285 \index{STORE32L} \index{STORE64L} \index{LOAD32L} \index{LOAD64L} |
|
|
286 \index{STORE32H} \index{STORE64H} \index{LOAD32H} \index{LOAD64H} \index{BSWAP} |
|
|
287 \begin{small} |
|
|
288 \begin{center} |
|
|
289 \begin{tabular}{|c|c|c|} |
|
|
290 \hline STORE32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 3]$ \\ |
|
|
291 \hline STORE64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[0 \ldots 7]$ \\ |
|
|
292 \hline LOAD32L(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[0 \ldots 3] \to x$ \\ |
|
|
293 \hline LOAD64L(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[0 \ldots 7] \to x$ \\ |
|
|
294 \hline STORE32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $x \to y[3 \ldots 0]$ \\ |
|
|
295 \hline STORE64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $x \to y[7 \ldots 0]$ \\ |
|
|
296 \hline LOAD32H(x, y) & {\bf unsigned long} x, {\bf unsigned char} *y & $y[3 \ldots 0] \to x$ \\ |
|
|
297 \hline LOAD64H(x, y) & {\bf unsigned long long} x, {\bf unsigned char} *y & $y[7 \ldots 0] \to x$ \\ |
|
|
298 \hline BSWAP(x) & {\bf unsigned long} x & Swaps the byte order of x. \\ |
|
|
299 \hline |
|
|
300 \end{tabular} |
|
|
301 \end{center} |
|
|
302 \end{small} |
|
|
303 |
|
|
304 There are 32-bit cyclic rotations as well: |
|
|
305 \index{ROL} \index{ROR} |
|
|
306 \begin{center} |
|
|
307 \begin{tabular}{|c|c|c|} |
|
|
308 \hline ROL(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x << y$ \\ |
|
|
309 \hline ROR(x, y) & {\bf unsigned long} x, {\bf unsigned long} y & $x >> y$ \\ |
|
|
310 \hline |
|
|
311 \end{tabular} |
|
|
312 \end{center} |
|
|
313 |
|
|
314 \section{Functions with Variable Length Output} |
|
|
315 Certain functions such as (for example) ``rsa\_export()'' give an output that is variable length. To prevent buffer overflows you |
|
|
316 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 |
|
|
317 the output will be stored. For example: |
|
|
318 \begin{small} |
|
|
319 \begin{verbatim} |
|
|
320 #include <mycrypt.h> |
|
|
321 int main(void) { |
|
|
322 rsa_key key; |
|
|
323 unsigned char buffer[1024]; |
|
|
324 unsigned long x; |
|
15
|
325 int err; |
|
3
|
326 |
|
|
327 /* ... Make up the RSA key somehow */ |
|
|
328 |
|
|
329 /* lets export the key, set x to the size of the output buffer */ |
|
|
330 x = sizeof(buffer); |
|
15
|
331 if ((err = rsa_export(buffer, &x, PK_PUBLIC, &key)) != CRYPT_OK) { |
|
|
332 printf("Export error: %s\n", error_to_string(err)); |
|
3
|
333 return -1; |
|
|
334 } |
|
|
335 |
|
|
336 /* if rsa_export() was successful then x will have the size of the output */ |
|
|
337 printf("RSA exported key takes %d bytes\n", x); |
|
|
338 |
|
|
339 /* ... do something with the buffer */ |
|
|
340 |
|
|
341 return 0; |
|
|
342 } |
|
|
343 \end{verbatim} |
|
|
344 \end{small} |
|
|
345 In the above example if the size of the RSA public key was more than 1024 bytes this function would not store anything in |
|
|
346 either ``buffer'' or ``x'' and simply return an error code. If the function suceeds it stores the length of the output |
|
|
347 back into ``x'' so that the calling application will know how many bytes used. |
|
|
348 |
|
|
349 \section{Functions that need a PRNG} |
|
|
350 Certain functions such as ``rsa\_make\_key()'' require a PRNG. These functions do not setup the PRNG themselves so it is |
|
|
351 the responsibility of the calling function to initialize the PRNG before calling them. |
|
|
352 |
|
|
353 \section{Functions that use Arrays of Octets} |
|
|
354 Most functions require inputs that are arrays of the data type ``unsigned char''. Whether it is a symmetric key, IV |
|
|
355 for a chaining mode or public key packet it is assumed that regardless of the actual size of ``unsigned char'' only the |
|
|
356 lower eight bits contain data. For example, if you want to pass a 256 bit key to a symmetric ciphers setup routine |
|
|
357 you must pass it in (a pointer to) an array of 32 ``unsigned char'' variables. Certain routines |
|
|
358 (such as SAFER+) take special care to work properly on platforms where an ``unsigned char'' is not eight bits. |
|
|
359 |
|
|
360 For the purposes of this library the term ``byte'' will refer to an octet or eight bit word. Typically an array of |
|
|
361 type ``byte'' will be synonymous with an array of type ``unsigned char''. |
|
|
362 |
|
|
363 \chapter{Symmetric Block Ciphers} |
|
|
364 \section{Core Functions} |
|
|
365 |
|
|
366 Libtomcrypt provides several block ciphers all in a plain vanilla ECB block mode. Its important to first note that you |
|
|
367 should never use the ECB modes directly to encrypt data. Instead you should use the ECB functions to make a chaining mode |
|
|
368 or use one of the provided chaining modes. All of the ciphers are written as ECB interfaces since it allows the rest of |
|
|
369 the API to grow in a modular fashion. |
|
|
370 |
|
|
371 All ciphers store their scheduled keys in a single data type called ``symmetric\_key''. This allows all ciphers to |
|
|
372 have the same prototype and store their keys as naturally as possible. All ciphers provide five visible functions which |
|
|
373 are (given that XXX is the name of the cipher): |
|
|
374 \index{Cipher Setup} |
|
|
375 \begin{verbatim} |
|
|
376 int XXX_setup(const unsigned char *key, int keylen, int rounds, |
|
|
377 symmetric_key *skey); |
|
|
378 \end{verbatim} |
|
|
379 |
|
|
380 The XXX\_setup() routine will setup the cipher to be used with a given number of rounds and a given key length (in bytes). |
|
|
381 The number of rounds can be set to zero to use the default, which is generally a good idea. |
|
|
382 |
|
|
383 If the function returns successfully the variable ``skey'' will have a scheduled key stored in it. Its important to note |
|
|
384 that you should only used this scheduled key with the intended cipher. For example, if you call |
|
|
385 ``blowfish\_setup()'' do not pass the scheduled key onto ``rc5\_ecb\_encrypt()''. All setup functions do not allocate |
|
|
386 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). |
|
|
387 |
|
|
388 To encrypt or decrypt a block in ECB mode there are these two functions: |
|
|
389 \index{Cipher Encrypt} \index{Cipher Decrypt} |
|
|
390 \begin{verbatim} |
|
|
391 void XXX_ecb_encrypt(const unsigned char *pt, unsigned char *ct, |
|
|
392 symmetric_key *skey); |
|
|
393 |
|
|
394 void XXX_ecb_decrypt(const unsigned char *ct, unsigned char *pt, |
|
|
395 symmetric_key *skey); |
|
|
396 \end{verbatim} |
|
|
397 These two functions will encrypt or decrypt (respectively) a single block of text\footnote{The size of which depends on |
|
|
398 which cipher you are using.} and store the result where you want it. It is possible that the input and output buffer are |
|
|
399 the same buffer. For the encrypt function ``pt''\footnote{pt stands for plaintext.} is the input and ``ct'' is the output. |
|
|
400 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} |
|
|
401 \begin{verbatim} |
|
|
402 int XXX_test(void); |
|
|
403 \end{verbatim} |
|
|
404 This function will return {\bf CRYPT\_OK} if the cipher matches the test vectors from the design publication it is |
|
|
405 based upon. Finally for each cipher there is a function which will help find a desired key size: |
|
|
406 \begin{verbatim} |
|
|
407 int XXX_keysize(int *keysize); |
|
|
408 \end{verbatim} |
|
|
409 Essentially it will round the input keysize in ``keysize'' down to the next appropriate key size. This function |
|
|
410 return {\bf CRYPT\_OK} if the key size specified is acceptable. For example: |
|
|
411 \begin{small} |
|
|
412 \begin{verbatim} |
|
|
413 #include <mycrypt.h> |
|
|
414 int main(void) |
|
|
415 { |
|
15
|
416 int keysize, err; |
|
3
|
417 |
|
|
418 /* now given a 20 byte key what keysize does Twofish want to use? */ |
|
|
419 keysize = 20; |
|
15
|
420 if ((err = twofish_keysize(&keysize)) != CRYPT_OK) { |
|
|
421 printf("Error getting key size: %s\n", error_to_string(err)); |
|
3
|
422 return -1; |
|
|
423 } |
|
|
424 printf("Twofish suggested a key size of %d\n", keysize); |
|
|
425 return 0; |
|
|
426 } |
|
|
427 \end{verbatim} |
|
|
428 \end{small} |
|
|
429 This should indicate a keysize of sixteen bytes is suggested. An example snippet that encodes a block with |
|
|
430 Blowfish in ECB mode is below. |
|
|
431 |
|
|
432 \begin{small} |
|
|
433 \begin{verbatim} |
|
|
434 #include <mycrypt.h> |
|
|
435 int main(void) |
|
|
436 { |
|
|
437 unsigned char pt[8], ct[8], key[8]; |
|
|
438 symmetric_key skey; |
|
15
|
439 int err; |
|
3
|
440 |
|
|
441 /* ... key is loaded appropriately in ``key'' ... */ |
|
|
442 /* ... load a block of plaintext in ``pt'' ... */ |
|
|
443 |
|
|
444 /* schedule the key */ |
|
15
|
445 if ((err = blowfish_setup(key, /* the key we will use */ |
|
|
446 8, /* key is 8 bytes (64-bits) long */ |
|
|
447 0, /* 0 == use default # of rounds */ |
|
|
448 &skey) /* where to put the scheduled key */ |
|
|
449 ) != CRYPT_OK) { |
|
|
450 printf("Setup error: %s\n", error_to_string(err)); |
|
3
|
451 return -1; |
|
|
452 } |
|
|
453 |
|
|
454 /* encrypt the block */ |
|
15
|
455 blowfish_ecb_encrypt(pt, /* encrypt this 8-byte array */ |
|
|
456 ct, /* store encrypted data here */ |
|
|
457 &skey); /* our previously scheduled key */ |
|
3
|
458 |
|
|
459 /* decrypt the block */ |
|
15
|
460 blowfish_ecb_decrypt(ct, /* decrypt this 8-byte array */ |
|
|
461 pt, /* store decrypted data here */ |
|
|
462 &skey); /* our previously scheduled key */ |
|
3
|
463 |
|
|
464 return 0; |
|
|
465 } |
|
|
466 \end{verbatim} |
|
|
467 \end{small} |
|
|
468 |
|
|
469 \section{Key Sizes and Number of Rounds} |
|
|
470 \index{Symmetric Keys} |
|
|
471 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 |
|
|
472 keys (mainly for test vectors anyways). Ideally your application should be making at least 256 bit keys. This is not |
|
|
473 because you're supposed to be paranoid. Its because if your PRNG has a bias of any sort the more bits the better. For |
|
|
474 example, if you have $\mbox{Pr}\left[X = 1\right] = {1 \over 2} \pm \gamma$ where $\vert \gamma \vert > 0$ then the |
|
|
475 total amount of entropy in N bits is $N \cdot -log_2\left ({1 \over 2} + \vert \gamma \vert \right)$. So if $\gamma$ |
|
|
476 were $0.25$ (a severe bias) a 256-bit string would have about 106 bits of entropy whereas a 128-bit string would have |
|
|
477 only 53 bits of entropy. |
|
|
478 |
|
|
479 The number of rounds of most ciphers is not an option you can change. Only RC5 allows you to change the number of |
|
|
480 rounds. By passing zero as the number of rounds all ciphers will use their default number of rounds. Generally the |
|
|
481 ciphers are configured such that the default number of rounds provide adequate security for the given block size. |
|
|
482 |
|
|
483 \section{The Cipher Descriptors} |
|
|
484 \index{Cipher Descriptor} |
|
|
485 To facilitate automatic routines an array of cipher descriptors is provided in the array ``cipher\_descriptor''. An element |
|
|
486 of this array has the following format: |
|
|
487 |
|
|
488 \begin{verbatim} |
|
|
489 struct _cipher_descriptor { |
|
|
490 char *name; |
|
|
491 unsigned long min_key_length, max_key_length, |
|
|
492 block_length, default_rounds; |
|
|
493 int (*setup) (const unsigned char *key, int keylength, |
|
|
494 int num_rounds, symmetric_key *skey); |
|
|
495 void (*ecb_encrypt)(const unsigned char *pt, unsigned char *ct, |
|
|
496 symmetric_key *key); |
|
|
497 void (*ecb_decrypt)(const unsigned char *ct, unsigned char *pt, |
|
|
498 symmetric_key *key); |
|
|
499 int (*test) (void); |
|
|
500 int (*keysize) (int *desired_keysize); |
|
|
501 }; |
|
|
502 \end{verbatim} |
|
|
503 |
|
|
504 Where ``name'' is the lower case ASCII version of the name. The fields ``min\_key\_length'', ``max\_key\_length'' and |
|
|
505 ``block\_length'' are all the number of bytes not bits. As a good rule of thumb it is assumed that the cipher supports |
|
|
506 the min and max key lengths but not always everything in between. The ``default\_rounds'' field is the default number |
|
|
507 of rounds that will be used. |
|
|
508 |
|
|
509 The remaining fields are all pointers to the core functions for each cipher. The end of the cipher\_descriptor array is |
|
|
510 marked when ``name'' equals {\bf NULL}. |
|
|
511 |
|
|
512 As of this release the current cipher\_descriptors elements are |
|
|
513 |
|
15
|
514 \index{Cipher descriptor table} |
|
3
|
515 \begin{small} |
|
|
516 \begin{center} |
|
|
517 \begin{tabular}{|c|c|c|c|c|c|} |
|
|
518 \hline Name & Descriptor Name & Block Size & Key Range & Rounds \\ |
|
|
519 \hline Blowfish & blowfish\_desc & 8 & 8 $\ldots$ 56 & 16 \\ |
|
|
520 \hline X-Tea & xtea\_desc & 8 & 16 & 32 \\ |
|
|
521 \hline RC2 & rc2\_desc & 8 & 8 $\ldots$ 128 & 16 \\ |
|
|
522 \hline RC5-32/12/b & rc5\_desc & 8 & 8 $\ldots$ 128 & 12 $\ldots$ 24 \\ |
|
|
523 \hline RC6-32/20/b & rc6\_desc & 16 & 8 $\ldots$ 128 & 20 \\ |
|
|
524 \hline SAFER+ & saferp\_desc &16 & 16, 24, 32 & 8, 12, 16 \\ |
|
|
525 \hline Safer K64 & safer\_k64\_desc & 8 & 8 & 6 $\ldots$ 13 \\ |
|
|
526 \hline Safer SK64 & safer\_sk64\_desc & 8 & 8 & 6 $\ldots$ 13 \\ |
|
|
527 \hline Safer K128 & safer\_k128\_desc & 8 & 16 & 6 $\ldots$ 13 \\ |
|
|
528 \hline Safer SK128 & safer\_sk128\_desc & 8 & 16 & 6 $\ldots$ 13 \\ |
|
|
529 \hline AES & aes\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\ |
|
15
|
530 & aes\_enc\_desc & 16 & 16, 24, 32 & 10, 12, 14 \\ |
|
3
|
531 \hline Twofish & twofish\_desc & 16 & 16, 24, 32 & 16 \\ |
|
|
532 \hline DES & des\_desc & 8 & 7 & 16 \\ |
|
|
533 \hline 3DES (EDE mode) & des3\_desc & 8 & 21 & 16 \\ |
|
|
534 \hline CAST5 (CAST-128) & cast5\_desc & 8 & 5 $\ldots$ 16 & 12, 16 \\ |
|
|
535 \hline Noekeon & noekeon\_desc & 16 & 16 & 16 \\ |
|
|
536 \hline Skipjack & skipjack\_desc & 8 & 10 & 32 \\ |
|
|
537 \hline |
|
|
538 \end{tabular} |
|
|
539 \end{center} |
|
|
540 \end{small} |
|
|
541 |
|
|
542 \subsection{Notes} |
|
15
|
543 \begin{small} |
|
|
544 \begin{enumerate} |
|
|
545 \item |
|
|
546 For AES (also known as Rijndael) there are four descriptors which complicate issues a little. The descriptors |
|
|
547 rijndael\_desc and rijndael\_enc\_desc provide the cipher named ``rijndael''. The descriptors aes\_desc and |
|
|
548 aes\_enc\_desc provide the cipher name ``aes''. Functionally both ``rijndael'' and ``aes'' are the same cipher. The |
|
|
549 only difference is when you call find\_cipher() you have to pass the correct name. The cipher descriptors with ``enc'' |
|
|
550 in the middle (e.g. rijndael\_enc\_desc) are related to an implementation of Rijndael with only the encryption routine |
|
|
551 and tables. The decryption and self--test function pointers of both ``encrypt only'' descriptors are set to \textbf{NULL} and |
|
|
552 should not be called. |
|
|
553 |
|
|
554 The ``encrypt only'' descriptors are useful for applications that only use the encryption function of the cipher. Algorithms such |
|
|
555 as EAX, PMAC and OMAC only require the encryption function. So far this ``encrypt only'' functionality has only been implemented for |
|
|
556 Rijndael as it makes the most sense for this cipher. |
|
|
557 |
|
|
558 \item |
|
3
|
559 For the 64-bit SAFER famliy of ciphers (e.g K64, SK64, K128, SK128) the ecb\_encrypt() and ecb\_decrypt() |
|
|
560 functions are the same. So if you want to use those functions directly just call safer\_ecb\_encrypt() |
|
|
561 or safer\_ecb\_decrypt() respectively. |
|
|
562 |
|
15
|
563 \item |
|
3
|
564 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 |
|
|
565 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 |
|
|
566 byte string from the real 7/21 byte key. |
|
|
567 |
|
15
|
568 \item |
|
3
|
569 Note that ``Twofish'' has additional configuration options that take place at build time. These options are found in |
|
|
570 the file ``mycrypt\_cfg.h''. The first option is ``TWOFISH\_SMALL'' which when defined will force the Twofish code |
|
|
571 to not pre-compute the Twofish ``$g(X)$'' function as a set of four $8 \times 32$ s-boxes. This means that a scheduled |
|
|
572 key will require less ram but the resulting cipher will be slower. The second option is ``TWOFISH\_TABLES'' which when |
|
|
573 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 |
|
|
574 by the polynomials 5B and EF used in the MDS multiplication. As a result the code is faster and slightly larger. The |
|
|
575 speed increase is useful when ``TWOFISH\_SMALL'' is defined since the s-boxes and MDS multiply form the heart of the |
|
|
576 Twofish round function. |
|
|
577 |
|
15
|
578 \index{Twofish build options} |
|
3
|
579 \begin{small} |
|
|
580 \begin{center} |
|
|
581 \begin{tabular}{|l|l|l|} |
|
|
582 \hline TWOFISH\_SMALL & TWOFISH\_TABLES & Speed and Memory (per key) \\ |
|
|
583 \hline undefined & undefined & Very fast, 4.2KB of ram. \\ |
|
|
584 \hline undefined & defined & As above, faster keysetup, larger code (1KB more). \\ |
|
|
585 \hline defined & undefined & Very slow, 0.2KB of ram. \\ |
|
|
586 \hline defined & defined & Somewhat faster, 0.2KB of ram, larger code. \\ |
|
|
587 \hline |
|
|
588 \end{tabular} |
|
|
589 \end{center} |
|
|
590 \end{small} |
|
|
591 |
|
15
|
592 \end{enumerate} |
|
|
593 \end{small} |
|
|
594 |
|
3
|
595 To work with the cipher\_descriptor array there is a function: |
|
15
|
596 \index{find\_cipher()} |
|
3
|
597 \begin{verbatim} |
|
|
598 int find_cipher(char *name) |
|
|
599 \end{verbatim} |
|
|
600 Which will search for a given name in the array. It returns negative one if the cipher is not found, otherwise it returns |
|
|
601 the location in the array where the cipher was found. For example, to indirectly setup Blowfish you can also use: |
|
|
602 \begin{small} |
|
|
603 \begin{verbatim} |
|
|
604 #include <mycrypt.h> |
|
|
605 int main(void) |
|
|
606 { |
|
|
607 unsigned char key[8]; |
|
|
608 symmetric_key skey; |
|
15
|
609 int err; |
|
3
|
610 |
|
|
611 /* you must register a cipher before you use it */ |
|
|
612 if (register_cipher(&blowfish_desc)) == -1) { |
|
|
613 printf("Unable to register Blowfish cipher."); |
|
|
614 return -1; |
|
|
615 } |
|
|
616 |
|
|
617 /* generic call to function (assuming the key in key[] was already setup) */ |
|
15
|
618 if ((err = cipher_descriptor[find_cipher("blowfish")].setup(key, 8, 0, &skey)) != CRYPT_OK) { |
|
|
619 printf("Error setting up Blowfish: %s\n", error_to_string(err)); |
|
3
|
620 return -1; |
|
|
621 } |
|
|
622 |
|
|
623 /* ... use cipher ... */ |
|
|
624 } |
|
|
625 \end{verbatim} |
|
|
626 \end{small} |
|
|
627 |
|
|
628 A good safety would be to check the return value of ``find\_cipher()'' before accessing the desired function. In order |
|
|
629 to use a cipher with the descriptor table you must register it first using: |
|
15
|
630 \index{register\_cipher()} |
|
3
|
631 \begin{verbatim} |
|
|
632 int register_cipher(const struct _cipher_descriptor *cipher); |
|
|
633 \end{verbatim} |
|
|
634 Which accepts a pointer to a descriptor and returns the index into the global descriptor table. If an error occurs such |
|
|
635 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 |
|
|
636 than once it will just return the index of the first copy. To remove a cipher call: |
|
15
|
637 \index{unregister\_cipher()} |
|
3
|
638 \begin{verbatim} |
|
|
639 int unregister_cipher(const struct _cipher_descriptor *cipher); |
|
|
640 \end{verbatim} |
|
|
641 Which returns {\bf CRYPT\_OK} if it removes it otherwise it returns {\bf CRYPT\_ERROR}. Consider: |
|
|
642 \begin{small} |
|
|
643 \begin{verbatim} |
|
|
644 #include <mycrypt.h> |
|
|
645 int main(void) |
|
|
646 { |
|
15
|
647 int err; |
|
3
|
648 |
|
|
649 /* register the cipher */ |
|
|
650 if (register_cipher(&rijndael_desc) == -1) { |
|
|
651 printf("Error registering Rijndael\n"); |
|
|
652 return -1; |
|
|
653 } |
|
|
654 |
|
|
655 /* use Rijndael */ |
|
|
656 |
|
|
657 /* remove it */ |
|
15
|
658 if ((err = unregister_cipher(&rijndael_desc)) != CRYPT_OK) { |
|
|
659 printf("Error removing Rijndael: %s\n", error_to_string(err)); |
|
3
|
660 return -1; |
|
|
661 } |
|
|
662 |
|
|
663 return 0; |
|
|
664 } |
|
|
665 \end{verbatim} |
|
|
666 \end{small} |
|
|
667 This snippet is a small program that registers only Rijndael only. |
|
|
668 |
|
|
669 \section{Symmetric Modes of Operations} |
|
|
670 \subsection{Background} |
|
|
671 A typical symmetric block cipher can be used in chaining modes to effectively encrypt messages larger than the block |
|
|
672 size of the cipher. Given a key $k$, a plaintext $P$ and a cipher $E$ we shall denote the encryption of the block |
|
|
673 $P$ under the key $k$ as $E_k(P)$. In some modes there exists an initial vector denoted as $C_{-1}$. |
|
|
674 |
|
|
675 \subsubsection{ECB Mode} |
|
15
|
676 \index{ECB mode} |
|
3
|
677 ECB or Electronic Codebook Mode is the simplest method to use. It is given as: |
|
|
678 \begin{equation} |
|
|
679 C_i = E_k(P_i) |
|
|
680 \end{equation} |
|
|
681 This mode is very weak since it allows people to swap blocks and perform replay attacks if the same key is used more |
|
|
682 than once. |
|
|
683 |
|
|
684 \subsubsection{CBC Mode} |
|
15
|
685 \index{CBC mode} |
|
3
|
686 CBC or Cipher Block Chaining mode is a simple mode designed to prevent trivial forms of replay and swap attacks on ciphers. |
|
|
687 It is given as: |
|
|
688 \begin{equation} |
|
|
689 C_i = E_k(P_i \oplus C_{i - 1}) |
|
|
690 \end{equation} |
|
|
691 It is important that the initial vector be unique and preferably random for each message encrypted under the same key. |
|
|
692 |
|
|
693 \subsubsection{CTR Mode} |
|
15
|
694 \index{CTR mode} |
|
3
|
695 CTR or Counter Mode is a mode which only uses the encryption function of the cipher. Given a initial vector which is |
|
|
696 treated as a large binary counter the CTR mode is given as: |
|
|
697 \begin{eqnarray} |
|
|
698 C_{-1} = C_{-1} + 1\mbox{ }(\mbox{mod }2^W) \nonumber \\ |
|
|
699 C_i = P_i \oplus E_k(C_{-1}) |
|
|
700 \end{eqnarray} |
|
|
701 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 |
|
|
702 encrypted under the same key replay and swap attacks are infeasible. CTR mode may look simple but it is as secure |
|
|
703 as the block cipher is under a chosen plaintext attack (provided the initial vector is unique). |
|
|
704 |
|
|
705 \subsubsection{CFB Mode} |
|
15
|
706 \index{CFB mode} |
|
3
|
707 CFB or Ciphertext Feedback Mode is a mode akin to CBC. It is given as: |
|
|
708 \begin{eqnarray} |
|
|
709 C_i = P_i \oplus C_{-1} \nonumber \\ |
|
|
710 C_{-1} = E_k(C_i) |
|
|
711 \end{eqnarray} |
|
|
712 Note that in this library the output feedback width is equal to the size of the block cipher. That is this mode is used |
|
|
713 to encrypt whole blocks at a time. However, the library will buffer data allowing the user to encrypt or decrypt partial |
|
|
714 blocks without a delay. When this mode is first setup it will initially encrypt the initial vector as required. |
|
|
715 |
|
|
716 \subsubsection{OFB Mode} |
|
15
|
717 \index{OFB mode} |
|
3
|
718 OFB or Output Feedback Mode is a mode akin to CBC as well. It is given as: |
|
|
719 \begin{eqnarray} |
|
|
720 C_{-1} = E_k(C_{-1}) \nonumber \\ |
|
|
721 C_i = P_i \oplus C_{-1} |
|
|
722 \end{eqnarray} |
|
|
723 Like the CFB mode the output width in CFB mode is the same as the width of the block cipher. OFB mode will also |
|
|
724 buffer the output which will allow you to encrypt or decrypt partial blocks without delay. |
|
|
725 |
|
|
726 \subsection{Choice of Mode} |
|
|
727 My personal preference is for the CTR mode since it has several key benefits: |
|
|
728 \begin{enumerate} |
|
|
729 \item No short cycles which is possible in the OFB and CFB modes. |
|
|
730 \item Provably as secure as the block cipher being used under a chosen plaintext attack. |
|
|
731 \item Technically does not require the decryption routine of the cipher. |
|
|
732 \item Allows random access to the plaintext. |
|
|
733 \item Allows the encryption of block sizes that are not equal to the size of the block cipher. |
|
|
734 \end{enumerate} |
|
|
735 The CTR, CFB and OFB routines provided allow you to encrypt block sizes that differ from the ciphers block size. They |
|
|
736 accomplish this by buffering the data required to complete a block. This allows you to encrypt or decrypt any size |
|
|
737 block of memory with either of the three modes. |
|
|
738 |
|
|
739 The ECB and CBC modes process blocks of the same size as the cipher at a time. Therefore they are less flexible than the |
|
|
740 other modes. |
|
|
741 |
|
|
742 \subsection{Implementation} |
|
|
743 \index{CBC Mode} \index{CTR Mode} |
|
|
744 \index{OFB Mode} \index{CFB Mode} |
|
|
745 The library provides simple support routines for handling CBC, CTR, CFB, OFB and ECB encoded messages. Assuming the mode |
|
|
746 you want is XXX there is a structure called ``symmetric\_XXX'' that will contain the information required to |
|
|
747 use that mode. They have identical setup routines (except ECB mode for obvious reasons): |
|
15
|
748 \index{ecb\_start()} \index{cfb\_start()} \index{cbc\_start()} \index{ofb\_start()} \index{ctr\_start()} |
|
3
|
749 \begin{verbatim} |
|
|
750 int XXX_start(int cipher, const unsigned char *IV, |
|
|
751 const unsigned char *key, int keylen, |
|
|
752 int num_rounds, symmetric_XXX *XXX); |
|
|
753 |
|
|
754 int ecb_start(int cipher, const unsigned char *key, int keylen, |
|
|
755 int num_rounds, symmetric_ECB *ecb); |
|
|
756 \end{verbatim} |
|
|
757 |
|
|
758 In each case ``cipher'' is the index into the cipher\_descriptor array of the cipher you want to use. The ``IV'' value is |
|
|
759 the initialization vector to be used with the cipher. You must fill the IV yourself and it is assumed they are the same |
|
|
760 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.} |
|
|
761 of the cipher you choose. It is important that the IV be random for each unique message you want to encrypt. The |
|
|
762 parameters ``key'', ``keylen'' and ``num\_rounds'' are the same as in the XXX\_setup() function call. The final parameter |
|
|
763 is a pointer to the structure you want to hold the information for the mode of operation. |
|
|
764 |
|
|
765 Both routines return {\bf CRYPT\_OK} if the cipher initialized correctly, otherwise they return an error code. To |
|
|
766 actually encrypt or decrypt the following routines are provided: |
|
15
|
767 \index{ecb\_encrypt()} \index{ecb\_decrypt()} \index{cfb\_encrypt()} \index{cfb\_decrypt()} |
|
|
768 \index{cbc\_encrypt()} \index{cbc\_decrypt()} \index{ofb\_encrypt()} \index{ofb\_decrypt()} \index{ctr\_encrypt()} \index{ctr\_decrypt()} |
|
3
|
769 \begin{verbatim} |
|
|
770 int XXX_encrypt(const unsigned char *pt, unsigned char *ct, |
|
|
771 symmetric_XXX *XXX); |
|
|
772 int XXX_decrypt(const unsigned char *ct, unsigned char *pt, |
|
|
773 symmetric_XXX *XXX); |
|
|
774 |
|
|
775 int YYY_encrypt(const unsigned char *pt, unsigned char *ct, |
|
|
776 unsigned long len, symmetric_YYY *YYY); |
|
|
777 int YYY_decrypt(const unsigned char *ct, unsigned char *pt, |
|
|
778 unsigned long len, symmetric_YYY *YYY); |
|
|
779 \end{verbatim} |
|
|
780 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 |
|
|
781 size of the buffer (as number of chars) to encrypt or decrypt. The CTR, OFB and CFB modes are order sensitive but not |
|
|
782 chunk sensitive. That is you can encrypt ``ABCDEF'' in three calls like ``AB'', ``CD'', ``EF'' or two like ``ABCDE'' and ``F'' |
|
|
783 and end up with the same ciphertext. However, encrypting ``ABC'' and ``DABC'' will result in different ciphertexts. All |
|
|
784 five of the modes will return {\bf CRYPT\_OK} on success from the encrypt or decrypt functions. |
|
|
785 |
|
|
786 To decrypt in either mode you simply perform the setup like before (recall you have to fetch the IV value you used) |
|
15
|
787 and use the decrypt routine on all of the blocks. |
|
|
788 |
|
|
789 To change or read the IV of a previously initialized chaining mode use the following two functions. |
|
|
790 |
|
|
791 \index{cbc\_setiv()} \index{cbc\_getiv()} \index{ofb\_setiv()} \index{ofb\_getiv()} \index{cfb\_setiv()} \index{cfb\_getiv()} |
|
|
792 \index{ctr\_setiv()} \index{ctr\_getiv()} |
|
|
793 \begin{verbatim} |
|
|
794 int XXX_getiv(unsigned char *IV, unsigned long *len, symmetric_XXX *XXX); |
|
|
795 int XXX_setiv(const unsigned char *IV, unsigned long len, symmetric_XXX *XXX); |
|
|
796 \end{verbatim} |
|
|
797 |
|
|
798 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 |
|
|
799 stored in ``len''. The XXX\_setiv will initialize the chaining mode state as if the original IV were the new IV specified. The length |
|
|
800 of the IV passed in must be the size of the ciphers block size. |
|
|
801 |
|
|
802 The XXX\_setiv functions are handy if you wish to change the IV without re--keying the cipher. |
|
|
803 |
|
3
|
804 \newpage |
|
|
805 \begin{small} |
|
|
806 \begin{verbatim} |
|
|
807 #include <mycrypt.h> |
|
|
808 int main(void) |
|
|
809 { |
|
|
810 unsigned char key[16], IV[16], buffer[512]; |
|
|
811 symmetric_CTR ctr; |
|
15
|
812 int x, err; |
|
3
|
813 |
|
|
814 /* register twofish first */ |
|
|
815 if (register_cipher(&twofish_desc) == -1) { |
|
|
816 printf("Error registering cipher.\n"); |
|
|
817 return -1; |
|
|
818 } |
|
|
819 |
|
|
820 /* somehow fill out key and IV */ |
|
|
821 |
|
|
822 /* start up CTR mode */ |
|
15
|
823 if ((err = ctr_start(find_cipher("twofish"), /* index of desired cipher */ |
|
|
824 IV, /* the initial vector */ |
|
|
825 key, /* the secret key */ |
|
|
826 16, /* length of secret key (16 bytes, 128 bits) */ |
|
|
827 0, /* 0 == default # of rounds */ |
|
|
828 &ctr) /* where to store initialized CTR state */ |
|
|
829 ) != CRYPT_OK) { |
|
|
830 printf("ctr_start error: %s\n", error_to_string(err)); |
|
3
|
831 return -1; |
|
|
832 } |
|
|
833 |
|
|
834 /* somehow fill buffer than encrypt it */ |
|
15
|
835 if ((err = ctr_encrypt( buffer, /* plaintext */ |
|
|
836 buffer, /* ciphertext */ |
|
|
837 sizeof(buffer), /* length of data to encrypt */ |
|
|
838 &ctr) /* previously initialized CTR state */ |
|
|
839 ) != CRYPT_OK) { |
|
|
840 printf("ctr_encrypt error: %s\n", error_to_string(err)); |
|
3
|
841 return -1; |
|
|
842 } |
|
|
843 |
|
|
844 /* make use of ciphertext... */ |
|
|
845 |
|
15
|
846 /* now we want to decrypt so let's use ctr_setiv */ |
|
|
847 if ((err = ctr_setiv( IV, /* the initial IV we gave to ctr_start */ |
|
|
848 16, /* the IV is 16 bytes long */ |
|
|
849 &ctr) /* the ctr state we wish to modify */ |
|
|
850 ) != CRYPT_OK) { |
|
|
851 printf("ctr_setiv error: %s\n", error_to_string(err)); |
|
|
852 return -1; |
|
|
853 } |
|
|
854 |
|
|
855 if ((err = ctr_decrypt( buffer, /* ciphertext */ |
|
|
856 buffer, /* plaintext */ |
|
|
857 sizeof(buffer), /* length of data to encrypt */ |
|
|
858 &ctr) /* previously initialized CTR state */ |
|
|
859 ) != CRYPT_OK) { |
|
|
860 printf("ctr_decrypt error: %s\n", error_to_string(err)); |
|
|
861 return -1; |
|
|
862 } |
|
|
863 |
|
3
|
864 /* clear up and return */ |
|
|
865 zeromem(key, sizeof(key)); |
|
|
866 zeromem(&ctr, sizeof(ctr)); |
|
|
867 |
|
|
868 return 0; |
|
|
869 } |
|
|
870 \end{verbatim} |
|
|
871 \end{small} |
|
|
872 |
|
|
873 \section{Encrypt and Authenticate Modes} |
|
|
874 |
|
|
875 \subsection{EAX Mode} |
|
|
876 LibTomCrypt provides support for a mode called EAX\footnote{See |
|
|
877 M. Bellare, P. Rogaway, D. Wagner, A Conventional Authenticated-Encryption Mode.} in a manner similar to the |
|
15
|
878 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. |
|
|
879 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.}. |
|
|
880 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 |
|
|
881 secret symmetric key. |
|
3
|
882 |
|
|
883 The ``header'' data is meant to be meta-data associated with a stream that isn't private (e.g. protocol messages). It can |
|
|
884 be added at anytime during an EAX stream and is part of the authentication tag. That is, changes in the meta-data can |
|
15
|
885 be detected by changes in the output tag. |
|
3
|
886 |
|
|
887 The mode can then process plaintext producing ciphertext as well as compute a partial checksum. The actual checksum |
|
|
888 called a ``tag'' is only emitted when the message is finished. In the interim though the user can process any arbitrary |
|
|
889 sized message block to send to the recipient as ciphertext. This makes the EAX mode especially suited for streaming modes |
|
|
890 of operation. |
|
|
891 |
|
|
892 The mode is initialized with the following function. |
|
15
|
893 \index{eax\_init()} |
|
3
|
894 \begin{verbatim} |
|
|
895 int eax_init(eax_state *eax, int cipher, |
|
|
896 const unsigned char *key, unsigned long keylen, |
|
|
897 const unsigned char *nonce, unsigned long noncelen, |
|
|
898 const unsigned char *header, unsigned long headerlen); |
|
|
899 \end{verbatim} |
|
|
900 |
|
|
901 Where ``eax'' is the EAX state. ``cipher'' is the index of the desired cipher in the descriptor table. |
|
|
902 ``key'' is the shared secret symmetric key of length ``keylen''. ``nonce'' is the random public string of |
|
|
903 length ``noncelen''. ``header'' is the random (or fixed or \textbf{NULL}) header for the message of length |
|
|
904 ``headerlen''. |
|
|
905 |
|
|
906 When this function completes ``eax'' will be initialized such that you can now either have data decrypted or |
|
15
|
907 encrypted in EAX mode. Note that if ``headerlen'' is zero you may pass ``header'' as \textbf{NULL} to indicate |
|
|
908 there is no initial header data. |
|
3
|
909 |
|
|
910 To encrypt or decrypt data in a streaming mode use the following. |
|
15
|
911 \index{eax\_encrypt()} \index{eax\_decrypt()} |
|
3
|
912 \begin{verbatim} |
|
|
913 int eax_encrypt(eax_state *eax, const unsigned char *pt, |
|
|
914 unsigned char *ct, unsigned long length); |
|
|
915 |
|
|
916 int eax_decrypt(eax_state *eax, const unsigned char *ct, |
|
|
917 unsigned char *pt, unsigned long length); |
|
|
918 \end{verbatim} |
|
|
919 The function ``eax\_encrypt'' will encrypt the bytes in ``pt'' of ``length'' bytes and store the ciphertext in |
|
|
920 ``ct''. Note that ``ct'' and ``pt'' may be the same region in memory. This function will also send the ciphertext |
|
|
921 through the OMAC function. The function ``eax\_decrypt'' decrypts ``ct'' and stores it in ``pt''. This also allows |
|
|
922 ``pt'' and ``ct'' to be the same region in memory. |
|
|
923 |
|
15
|
924 You cannot both encrypt or decrypt with the same ``eax'' context. For bi-directional communication you |
|
|
925 will need to initialize two EAX contexts (preferably with different headers and nonces). |
|
|
926 |
|
3
|
927 Note that both of these functions allow you to send the data in any granularity but the order is important. While |
|
|
928 the eax\_init() function allows you to add initial header data to the stream you can also add header data during the |
|
|
929 EAX stream with the following. |
|
|
930 |
|
15
|
931 \index{eax\_addheader()} |
|
3
|
932 \begin{verbatim} |
|
|
933 int eax_addheader(eax_state *eax, |
|
|
934 const unsigned char *header, unsigned long length); |
|
|
935 \end{verbatim} |
|
|
936 |
|
|
937 This will add the ``length'' bytes from ``header'' to the given ``eax'' stream. Once the message is finished the |
|
|
938 ``tag'' (checksum) may be computed with the following function. |
|
|
939 |
|
15
|
940 \index{eax\_done()} |
|
3
|
941 \begin{verbatim} |
|
|
942 int eax_done(eax_state *eax, |
|
|
943 unsigned char *tag, unsigned long *taglen); |
|
|
944 \end{verbatim} |
|
|
945 This will terminate the EAX state ``eax'' and store upto ``taglen'' bytes of the message tag in ``tag''. The function |
|
|
946 then stores how many bytes of the tag were written out back into ``taglen''. |
|
|
947 |
|
|
948 The EAX mode code can be tested to ensure it matches the test vectors by calling the following function. |
|
15
|
949 \index{eax\_test()} |
|
3
|
950 \begin{verbatim} |
|
|
951 int eax_test(void); |
|
|
952 \end{verbatim} |
|
|
953 This requires that the AES (or Rijndael) block cipher be registered with the cipher\_descriptor table first. |
|
|
954 |
|
15
|
955 \begin{verbatim} |
|
|
956 #include <mycrypt.h> |
|
|
957 int main(void) |
|
|
958 { |
|
|
959 int err; |
|
|
960 eax_state eax; |
|
|
961 unsigned char pt[64], ct[64], nonce[16], key[16], tag[16]; |
|
|
962 unsigned long taglen; |
|
|
963 |
|
|
964 if (register_cipher(&rijndael_desc) == -1) { |
|
|
965 printf("Error registering Rijndael"); |
|
|
966 return EXIT_FAILURE; |
|
|
967 } |
|
|
968 |
|
|
969 /* ... make up random nonce and key ... */ |
|
|
970 |
|
|
971 /* initialize context */ |
|
|
972 if ((err = eax_init( &eax, /* the context */ |
|
|
973 find_cipher("rijndael"), /* cipher we want to use */ |
|
|
974 nonce, /* our state nonce */ |
|
|
975 16, /* none is 16 bytes */ |
|
|
976 "TestApp", /* example header, identifies this program */ |
|
|
977 7) /* length of the header */ |
|
|
978 ) != CRYPT_OK) { |
|
|
979 printf("Error eax_init: %s", error_to_string(err)); |
|
|
980 return EXIT_FAILURE; |
|
|
981 } |
|
|
982 |
|
|
983 /* now encrypt data, say in a loop or whatever */ |
|
|
984 if ((err = eax_encrypt( &eax, /* eax context */ |
|
|
985 pt, /* plaintext (source) */ |
|
|
986 ct, /* ciphertext (destination) */ |
|
|
987 sizeof(pt) /* size of plaintext */ |
|
|
988 ) != CRYPT_OK) { |
|
|
989 printf("Error eax_encrypt: %s", error_to_string(err)); |
|
|
990 return EXIT_FAILURE; |
|
|
991 } |
|
|
992 |
|
|
993 /* finish message and get authentication tag */ |
|
|
994 taglen = sizeof(tag); |
|
|
995 if ((err = eax_done( &eax, /* eax context */ |
|
|
996 tag, /* where to put tag */ |
|
|
997 &taglen /* length of tag space */ |
|
|
998 ) != CRYPT_OK) { |
|
|
999 printf("Error eax_done: %s", error_to_string(err)); |
|
|
1000 return EXIT_FAILURE; |
|
|
1001 } |
|
|
1002 |
|
|
1003 /* now we have the authentication tag in "tag" and it's taglen bytes long */ |
|
|
1004 |
|
|
1005 } |
|
|
1006 \end{verbatim} |
|
|
1007 |
|
|
1008 You can also perform an entire EAX state on a block of memory in a single function call with the |
|
|
1009 following functions. |
|
|
1010 |
|
|
1011 |
|
|
1012 \index{eax\_encrypt\_authenticate\_memory} \index{eax\_decrypt\_verify\_memory} |
|
|
1013 \begin{verbatim} |
|
|
1014 int eax_encrypt_authenticate_memory(int cipher, |
|
|
1015 const unsigned char *key, unsigned long keylen, |
|
|
1016 const unsigned char *nonce, unsigned long noncelen, |
|
|
1017 const unsigned char *header, unsigned long headerlen, |
|
|
1018 const unsigned char *pt, unsigned long ptlen, |
|
|
1019 unsigned char *ct, |
|
|
1020 unsigned char *tag, unsigned long *taglen); |
|
|
1021 |
|
|
1022 int eax_decrypt_verify_memory(int cipher, |
|
|
1023 const unsigned char *key, unsigned long keylen, |
|
|
1024 const unsigned char *nonce, unsigned long noncelen, |
|
|
1025 const unsigned char *header, unsigned long headerlen, |
|
|
1026 const unsigned char *ct, unsigned long ctlen, |
|
|
1027 unsigned char *pt, |
|
|
1028 unsigned char *tag, unsigned long taglen, |
|
|
1029 int *res); |
|
|
1030 \end{verbatim} |
|
|
1031 |
|
|
1032 Both essentially just call eax\_init() followed by eax\_encrypt() (or eax\_decrypt() respectively) and eax\_done(). The parameters |
|
|
1033 have the same meaning as with those respective functions. |
|
|
1034 |
|
|
1035 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 |
|
|
1036 the tag it computed while decrypting the message. If the tags match then it stores a $1$ in ``res'', otherwise it stores a $0$. |
|
|
1037 |
|
3
|
1038 \subsection{OCB Mode} |
|
|
1039 LibTomCrypt provides support for a mode called OCB\footnote{See |
|
|
1040 P. Rogaway, M. Bellare, J. Black, T. Krovetz, ``OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption''.} |
|
15
|
1041 . OCB is an encryption protocol that simultaneously provides authentication. It is slightly faster to use than EAX mode |
|
3
|
1042 but is less flexible. Let's review how to initialize an OCB context. |
|
|
1043 |
|
15
|
1044 \index{ocb\_init()} |
|
3
|
1045 \begin{verbatim} |
|
|
1046 int ocb_init(ocb_state *ocb, int cipher, |
|
|
1047 const unsigned char *key, unsigned long keylen, |
|
|
1048 const unsigned char *nonce); |
|
|
1049 \end{verbatim} |
|
|
1050 |
|
|
1051 This will initialize the ``ocb'' context using cipher descriptor ``cipher''. It will use a ``key'' of length ``keylen'' |
|
|
1052 and the random ``nonce''. Note that ``nonce'' must be a random (public) string the same length as the block ciphers |
|
15
|
1053 block size (e.g. 16 bytes for AES). |
|
3
|
1054 |
|
|
1055 This mode has no ``Associated Data'' like EAX mode does which means you cannot authenticate metadata along with the stream. |
|
|
1056 To encrypt or decrypt data use the following. |
|
|
1057 |
|
15
|
1058 \index{ocb\_encrypt()} \index{ocb\_decrypt()} |
|
3
|
1059 \begin{verbatim} |
|
|
1060 int ocb_encrypt(ocb_state *ocb, const unsigned char *pt, unsigned char *ct); |
|
|
1061 int ocb_decrypt(ocb_state *ocb, const unsigned char *ct, unsigned char *pt); |
|
|
1062 \end{verbatim} |
|
|
1063 |
|
|
1064 This will encrypt (or decrypt for the latter) a fixed length of data from ``pt'' to ``ct'' (vice versa for the latter). |
|
|
1065 They assume that ``pt'' and ``ct'' are the same size as the block cipher's block size. Note that you cannot call |
|
|
1066 both functions given a single ``ocb'' state. For bi-directional communication you will have to initialize two ``ocb'' |
|
|
1067 states (with different nonces). Also ``pt'' and ``ct'' may point to the same location in memory. |
|
|
1068 |
|
|
1069 When you are finished encrypting the message you call the following function to compute the tag. |
|
|
1070 |
|
15
|
1071 \index{ocb\_done\_encrypt()} |
|
3
|
1072 \begin{verbatim} |
|
|
1073 int ocb_done_encrypt(ocb_state *ocb, |
|
|
1074 const unsigned char *pt, unsigned long ptlen, |
|
|
1075 unsigned char *ct, |
|
|
1076 unsigned char *tag, unsigned long *taglen); |
|
|
1077 \end{verbatim} |
|
|
1078 |
|
|
1079 This will terminate an encrypt stream ``ocb''. If you have trailing bytes of plaintext that will not complete a block |
|
|
1080 you can pass them here. This will also encrypt the ``ptlen'' bytes in ``pt'' and store them in ``ct''. It will also |
|
|
1081 store upto ``taglen'' bytes of the tag into ``tag''. |
|
|
1082 |
|
|
1083 Note that ``ptlen'' must be less than or equal to the block size of block cipher chosen. Also note that if you have |
|
|
1084 an input message equal to the length of the block size then you pass the data here (not to ocb\_encrypt()) only. |
|
|
1085 |
|
|
1086 To terminate a decrypt stream and compared the tag you call the following. |
|
|
1087 |
|
15
|
1088 \index{ocb\_done\_decrypt()} |
|
3
|
1089 \begin{verbatim} |
|
|
1090 int ocb_done_decrypt(ocb_state *ocb, |
|
|
1091 const unsigned char *ct, unsigned long ctlen, |
|
|
1092 unsigned char *pt, |
|
|
1093 const unsigned char *tag, unsigned long taglen, |
|
|
1094 int *res); |
|
|
1095 \end{verbatim} |
|
|
1096 |
|
|
1097 Similarly to the previous function you can pass trailing message bytes into this function. This will compute the |
|
|
1098 tag of the message (internally) and then compare it against the ``taglen'' bytes of ``tag'' provided. By default |
|
|
1099 ``res'' is set to zero. If all ``taglen'' bytes of ``tag'' can be verified then ``res'' is set to one (authenticated |
|
|
1100 message). |
|
|
1101 |
|
|
1102 To make life simpler the following two functions are provided for memory bound OCB. |
|
|
1103 |
|
15
|
1104 \index{ocb\_encrypt\_authenticate\_memory()} |
|
3
|
1105 \begin{verbatim} |
|
|
1106 int ocb_encrypt_authenticate_memory(int cipher, |
|
|
1107 const unsigned char *key, unsigned long keylen, |
|
|
1108 const unsigned char *nonce, |
|
|
1109 const unsigned char *pt, unsigned long ptlen, |
|
|
1110 unsigned char *ct, |
|
|
1111 unsigned char *tag, unsigned long *taglen); |
|
|
1112 \end{verbatim} |
|
|
1113 |
|
|
1114 This will OCB encrypt the message ``pt'' of length ``ptlen'' and store the ciphertext in ``ct''. The length ``ptlen'' |
|
|
1115 can be any arbitrary length. |
|
|
1116 |
|
15
|
1117 \index{ocb\_decrypt\_verify\_memory()} |
|
3
|
1118 \begin{verbatim} |
|
|
1119 int ocb_decrypt_verify_memory(int cipher, |
|
|
1120 const unsigned char *key, unsigned long keylen, |
|
|
1121 const unsigned char *nonce, |
|
|
1122 const unsigned char *ct, unsigned long ctlen, |
|
|
1123 unsigned char *pt, |
|
|
1124 const unsigned char *tag, unsigned long taglen, |
|
|
1125 int *res); |
|
|
1126 \end{verbatim} |
|
|
1127 |
|
|
1128 Similarly this will OCB decrypt and compare the internally computed tag against the tag provided. ``res'' is set |
|
|
1129 appropriately. |
|
|
1130 |
|
|
1131 \chapter{One-Way Cryptographic Hash Functions} |
|
|
1132 \section{Core Functions} |
|
|
1133 |
|
|
1134 Like the ciphers there are hash core functions and a universal data type to hold the hash state called ``hash\_state''. |
|
|
1135 To initialize hash XXX (where XXX is the name) call: |
|
|
1136 \index{Hash Functions} |
|
|
1137 \begin{verbatim} |
|
|
1138 void XXX_init(hash_state *md); |
|
|
1139 \end{verbatim} |
|
|
1140 |
|
|
1141 This simply sets up the hash to the default state governed by the specifications of the hash. To add data to the |
|
|
1142 message being hashed call: |
|
|
1143 \begin{verbatim} |
|
|
1144 int XXX_process(hash_state *md, const unsigned char *in, unsigned long len); |
|
|
1145 \end{verbatim} |
|
|
1146 |
|
|
1147 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 |
|
|
1148 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 |
|
|
1149 (hash output) will be the same. For example, this means that: |
|
|
1150 \begin{verbatim} |
|
|
1151 md5_process(&md, "hello ", 6); |
|
|
1152 md5_process(&md, "world", 5); |
|
|
1153 \end{verbatim} |
|
|
1154 Will produce the same message digest as the single call: |
|
|
1155 \index{Message Digest} |
|
|
1156 \begin{verbatim} |
|
|
1157 md5_process(&md, "hello world", 11); |
|
|
1158 \end{verbatim} |
|
|
1159 |
|
|
1160 To finally get the message digest (the hash) call: |
|
|
1161 \begin{verbatim} |
|
|
1162 int XXX_done(hash_state *md, |
|
|
1163 unsigned char *out); |
|
|
1164 \end{verbatim} |
|
|
1165 |
|
|
1166 This function will finish up the hash and store the result in the ``out'' array. You must ensure that ``out'' is long |
|
|
1167 enough for the hash in question. Often hashes are used to get keys for symmetric ciphers so the ``XXX\_done()'' functions |
|
|
1168 will wipe the ``md'' variable before returning automatically. |
|
|
1169 |
|
|
1170 To test a hash function call: |
|
|
1171 \begin{verbatim} |
|
|
1172 int XXX_test(void); |
|
|
1173 \end{verbatim} |
|
|
1174 |
|
|
1175 This will return {\bf CRYPTO\_OK} if the hash matches the test vectors, otherwise it returns an error code. An |
|
|
1176 example snippet that hashes a message with md5 is given below. |
|
|
1177 \begin{small} |
|
|
1178 \begin{verbatim} |
|
|
1179 #include <mycrypt.h> |
|
|
1180 int main(void) |
|
|
1181 { |
|
|
1182 hash_state md; |
|
|
1183 unsigned char *in = "hello world", out[16]; |
|
|
1184 |
|
|
1185 /* setup the hash */ |
|
|
1186 md5_init(&md); |
|
|
1187 |
|
|
1188 /* add the message */ |
|
|
1189 md5_process(&md, in, strlen(in)); |
|
|
1190 |
|
|
1191 /* get the hash in out[0..15] */ |
|
|
1192 md5_done(&md, out); |
|
|
1193 |
|
|
1194 return 0; |
|
|
1195 } |
|
|
1196 \end{verbatim} |
|
|
1197 \end{small} |
|
|
1198 |
|
|
1199 \section{Hash Descriptors} |
|
|
1200 Like the set of ciphers the set of hashes have descriptors too. They are stored in an array called ``hash\_descriptor'' and |
|
|
1201 are defined by: |
|
|
1202 \begin{verbatim} |
|
|
1203 struct _hash_descriptor { |
|
|
1204 char *name; |
|
|
1205 unsigned long hashsize; /* digest output size in bytes */ |
|
|
1206 unsigned long blocksize; /* the block size the hash uses */ |
|
|
1207 void (*init) (hash_state *); |
|
|
1208 int (*process)(hash_state *, const unsigned char *, unsigned long); |
|
|
1209 int (*done) (hash_state *, unsigned char *); |
|
|
1210 int (*test) (void); |
|
|
1211 }; |
|
|
1212 \end{verbatim} |
|
|
1213 |
|
|
1214 Similarly ``name'' is the name of the hash function in ASCII (all lowercase). ``hashsize'' is the size of the digest output |
|
|
1215 in bytes. The remaining fields are pointers to the functions that do the respective tasks. There is a function to |
|
|
1216 search the array as well called ``int find\_hash(char *name)''. It returns -1 if the hash is not found, otherwise the |
|
|
1217 position in the descriptor table of the hash. |
|
|
1218 |
|
|
1219 You can use the table to indirectly call a hash function that is chosen at runtime. For example: |
|
|
1220 \begin{small} |
|
|
1221 \begin{verbatim} |
|
|
1222 #include <mycrypt.h> |
|
|
1223 int main(void) |
|
|
1224 { |
|
|
1225 unsigned char buffer[100], hash[MAXBLOCKSIZE]; |
|
|
1226 int idx, x; |
|
|
1227 hash_state md; |
|
|
1228 |
|
|
1229 /* register hashes .... */ |
|
|
1230 if (register_hash(&md5_desc) == -1) { |
|
|
1231 printf("Error registering MD5.\n"); |
|
|
1232 return -1; |
|
|
1233 } |
|
|
1234 |
|
|
1235 /* register other hashes ... */ |
|
|
1236 |
|
|
1237 /* prompt for name and strip newline */ |
|
|
1238 printf("Enter hash name: \n"); |
|
|
1239 fgets(buffer, sizeof(buffer), stdin); |
|
|
1240 buffer[strlen(buffer) - 1] = 0; |
|
|
1241 |
|
|
1242 /* get hash index */ |
|
|
1243 idx = find_hash(buffer); |
|
|
1244 if (idx == -1) { |
|
|
1245 printf("Invalid hash name!\n"); |
|
|
1246 return -1; |
|
|
1247 } |
|
|
1248 |
|
|
1249 /* hash input until blank line */ |
|
|
1250 hash_descriptor[idx].init(&md); |
|
|
1251 while (fgets(buffer, sizeof(buffer), stdin) != NULL) |
|
|
1252 hash_descriptor[idx].process(&md, buffer, strlen(buffer)); |
|
|
1253 hash_descriptor[idx].done(&md, hash); |
|
|
1254 |
|
|
1255 /* dump to screen */ |
|
|
1256 for (x = 0; x < hash_descriptor[idx].hashsize; x++) |
|
|
1257 printf("%02x ", hash[x]); |
|
|
1258 printf("\n"); |
|
|
1259 return 0; |
|
|
1260 } |
|
|
1261 \end{verbatim} |
|
|
1262 \end{small} |
|
|
1263 |
|
|
1264 Note the usage of ``MAXBLOCKSIZE''. In Libtomcrypt no symmetric block, key or hash digest is larger than MAXBLOCKSIZE in |
|
|
1265 length. This provides a simple size you can set your automatic arrays to that will not get overrun. |
|
|
1266 |
|
|
1267 There are three helper functions as well: |
|
|
1268 \index{hash\_memory()} \index{hash\_file()} |
|
|
1269 \begin{verbatim} |
|
|
1270 int hash_memory(int hash, const unsigned char *data, |
|
|
1271 unsigned long len, unsigned char *dst, |
|
|
1272 unsigned long *outlen); |
|
|
1273 |
|
|
1274 int hash_file(int hash, const char *fname, |
|
|
1275 unsigned char *dst, |
|
|
1276 unsigned long *outlen); |
|
|
1277 |
|
|
1278 int hash_filehandle(int hash, FILE *in, |
|
|
1279 unsigned char *dst, unsigned long *outlen); |
|
|
1280 \end{verbatim} |
|
|
1281 |
|
|
1282 The ``hash'' parameter is the location in the descriptor table of the hash (\textit{e.g. the return of find\_hash()}). |
|
|
1283 The ``*outlen'' variable is used to keep track of the output size. You |
|
|
1284 must set it to the size of your output buffer before calling the functions. When they complete succesfully they store |
|
|
1285 the length of the message digest back in it. The functions are otherwise straightforward. The ``hash\_filehandle'' |
|
|
1286 function assumes that ``in'' is an file handle opened in binary mode. It will hash to the end of file and not reset |
|
|
1287 the file position when finished. |
|
|
1288 |
|
|
1289 To perform the above hash with md5 the following code could be used: |
|
|
1290 \begin{small} |
|
|
1291 \begin{verbatim} |
|
|
1292 #include <mycrypt.h> |
|
|
1293 int main(void) |
|
|
1294 { |
|
15
|
1295 int idx, err; |
|
3
|
1296 unsigned long len; |
|
|
1297 unsigned char out[MAXBLOCKSIZE]; |
|
|
1298 |
|
|
1299 /* register the hash */ |
|
|
1300 if (register_hash(&md5_desc) == -1) { |
|
|
1301 printf("Error registering MD5.\n"); |
|
|
1302 return -1; |
|
|
1303 } |
|
|
1304 |
|
|
1305 /* get the index of the hash */ |
|
|
1306 idx = find_hash("md5"); |
|
|
1307 |
|
|
1308 /* call the hash */ |
|
|
1309 len = sizeof(out); |
|
15
|
1310 if ((err = hash_memory(idx, "hello world", 11, out, &len)) != CRYPT_OK) { |
|
|
1311 printf("Error hashing data: %s\n", error_to_string(err)); |
|
3
|
1312 return -1; |
|
|
1313 } |
|
|
1314 return 0; |
|
|
1315 } |
|
|
1316 \end{verbatim} |
|
|
1317 \end{small} |
|
|
1318 |
|
|
1319 The following hashes are provided as of this release: |
|
15
|
1320 \index{Hash descriptor table} |
|
3
|
1321 \begin{center} |
|
|
1322 \begin{tabular}{|c|c|c|} |
|
|
1323 \hline Name & Descriptor Name & Size of Message Digest (bytes) \\ |
|
|
1324 \hline WHIRLPOOL & whirlpool\_desc & 64 \\ |
|
|
1325 \hline SHA-512 & sha512\_desc & 64 \\ |
|
|
1326 \hline SHA-384 & sha384\_desc & 48 \\ |
|
|
1327 \hline SHA-256 & sha256\_desc & 32 \\ |
|
|
1328 \hline SHA-224 & sha224\_desc & 28 \\ |
|
|
1329 \hline TIGER-192 & tiger\_desc & 24 \\ |
|
|
1330 \hline SHA-1 & sha1\_desc & 20 \\ |
|
|
1331 \hline RIPEMD-160 & rmd160\_desc & 20 \\ |
|
|
1332 \hline RIPEMD-128 & rmd128\_desc & 16 \\ |
|
|
1333 \hline MD5 & md5\_desc & 16 \\ |
|
|
1334 \hline MD4 & md4\_desc & 16 \\ |
|
|
1335 \hline MD2 & md2\_desc & 16 \\ |
|
|
1336 \hline |
|
|
1337 \end{tabular} |
|
|
1338 \end{center} |
|
|
1339 |
|
|
1340 Similar to the cipher descriptor table you must register your hash algorithms before you can use them. These functions |
|
|
1341 work exactly like those of the cipher registration code. The functions are: |
|
15
|
1342 \index{register\_hash()} \index{unregister\_hash()} |
|
3
|
1343 \begin{verbatim} |
|
|
1344 int register_hash(const struct _hash_descriptor *hash); |
|
|
1345 int unregister_hash(const struct _hash_descriptor *hash); |
|
|
1346 \end{verbatim} |
|
|
1347 |
|
|
1348 \subsection{Notice} |
|
|
1349 It is highly recommended that you \textbf{not} use the MD4 or MD5 hashes for the purposes of digital signatures or authentication codes. |
|
|
1350 These hashes are provided for completeness and they still can be used for the purposes of password hashing or one-way accumulators |
|
|
1351 (e.g. Yarrow). |
|
|
1352 |
|
|
1353 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 |
|
|
1354 for all purposes you would normally use a hash for. |
|
|
1355 |
|
|
1356 \chapter{Message Authentication Codes} |
|
|
1357 \section{HMAC Protocol} |
|
|
1358 Thanks to Dobes Vandermeer the library now includes support for hash based message authenication codes or HMAC for short. An HMAC |
|
|
1359 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 |
|
|
1360 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 |
|
|
1361 eavesdropper will not be able to verify the authenticity of a message. |
|
|
1362 |
|
|
1363 The HMAC support works much like the normal hash functions except that the initialization routine requires you to pass a key |
|
|
1364 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 |
|
|
1365 chars. The initialization routine is: |
|
15
|
1366 \index{hmac\_init()} |
|
3
|
1367 \begin{verbatim} |
|
|
1368 int hmac_init(hmac_state *hmac, int hash, |
|
|
1369 const unsigned char *key, unsigned long keylen); |
|
|
1370 \end{verbatim} |
|
|
1371 The ``hmac'' parameter is the state for the HMAC code. ``hash'' is the index into the descriptor table of the hash you want |
|
|
1372 to use to authenticate the message. ``key'' is the pointer to the array of chars that make up the key. ``keylen'' is the |
|
|
1373 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: |
|
15
|
1374 \index{hmac\_process()} |
|
3
|
1375 \begin{verbatim} |
|
|
1376 int hmac_process(hmac_state *hmac, const unsigned char *buf, |
|
|
1377 unsigned long len); |
|
|
1378 \end{verbatim} |
|
|
1379 ``hmac'' is the HMAC state you are working with. ``buf'' is the array of octets to send into the HMAC process. ``len'' is the |
|
|
1380 number of octets to process. Like the hash process routines you can send the data in arbitrarly sized chunks. When you |
|
|
1381 are finished with the HMAC process you must call the following function to get the HMAC code: |
|
15
|
1382 \index{hmac\_done()} |
|
3
|
1383 \begin{verbatim} |
|
|
1384 int hmac_done(hmac_state *hmac, unsigned char *hashOut, |
|
|
1385 unsigned long *outlen); |
|
|
1386 \end{verbatim} |
|
|
1387 ``hmac'' is the HMAC state you are working with. ``hashOut'' is the array of octets where the HMAC code should be stored. You must |
|
|
1388 set ``outlen'' to the size of the destination buffer before calling this function. It is updated with the length of the HMAC code |
|
|
1389 produced (depending on which hash was picked). If ``outlen'' is less than the size of the message digest (and ultimately |
|
|
1390 the HMAC code) then the HMAC code is truncated as per FIPS-198 specifications (e.g. take the first ``outlen'' bytes). |
|
|
1391 |
|
|
1392 There are two utility functions provided to make using HMACs easier todo. They accept the key and information about the |
|
|
1393 message (file pointer, address in memory) and produce the HMAC result in one shot. These are useful if you want to avoid |
|
|
1394 calling the three step process yourself. |
|
|
1395 |
|
15
|
1396 \index{hmac\_memory()} |
|
3
|
1397 \begin{verbatim} |
|
|
1398 int hmac_memory(int hash, const unsigned char *key, unsigned long keylen, |
|
|
1399 const unsigned char *data, unsigned long len, |
|
|
1400 unsigned char *dst, unsigned long *dstlen); |
|
|
1401 \end{verbatim} |
|
|
1402 This will produce an HMAC code for the array of octets in ``data'' of length ``len''. The index into the hash descriptor |
|
|
1403 table must be provided in ``hash''. It uses the key from ``key'' with a key length of ``keylen''. |
|
|
1404 The result is stored in the array of octets ``dst'' and the length in ``dstlen''. The value of ``dstlen'' must be set |
|
|
1405 to the size of the destination buffer before calling this function. Similarly for files there is the following function: |
|
15
|
1406 \index{hmac\_file()} |
|
3
|
1407 \begin{verbatim} |
|
|
1408 int hmac_file(int hash, const char *fname, const unsigned char *key, |
|
|
1409 unsigned long keylen, |
|
|
1410 unsigned char *dst, unsigned long *dstlen); |
|
|
1411 \end{verbatim} |
|
|
1412 ``hash'' is the index into the hash descriptor table of the hash you want to use. ``fname'' is the filename to process. |
|
|
1413 ``key'' is the array of octets to use as the key of length ``keylen''. ``dst'' is the array of octets where the |
|
|
1414 result should be stored. |
|
|
1415 |
|
|
1416 To test if the HMAC code is working there is the following function: |
|
15
|
1417 \index{hmac\_test()} |
|
3
|
1418 \begin{verbatim} |
|
|
1419 int hmac_test(void); |
|
|
1420 \end{verbatim} |
|
|
1421 Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the |
|
|
1422 HMAC system is given below. |
|
|
1423 |
|
|
1424 \begin{small} |
|
|
1425 \begin{verbatim} |
|
|
1426 #include <mycrypt.h> |
|
|
1427 int main(void) |
|
|
1428 { |
|
15
|
1429 int idx, err; |
|
3
|
1430 hmac_state hmac; |
|
|
1431 unsigned char key[16], dst[MAXBLOCKSIZE]; |
|
|
1432 unsigned long dstlen; |
|
|
1433 |
|
|
1434 /* register SHA-1 */ |
|
|
1435 if (register_hash(&sha1_desc) == -1) { |
|
|
1436 printf("Error registering SHA1\n"); |
|
|
1437 return -1; |
|
|
1438 } |
|
|
1439 |
|
|
1440 /* get index of SHA1 in hash descriptor table */ |
|
|
1441 idx = find_hash("sha1"); |
|
|
1442 |
|
|
1443 /* we would make up our symmetric key in "key[]" here */ |
|
|
1444 |
|
|
1445 /* start the HMAC */ |
|
15
|
1446 if ((err = hmac_init(&hmac, idx, key, 16)) != CRYPT_OK) { |
|
|
1447 printf("Error setting up hmac: %s\n", error_to_string(err)); |
|
3
|
1448 return -1; |
|
|
1449 } |
|
|
1450 |
|
|
1451 /* process a few octets */ |
|
15
|
1452 if((err = hmac_process(&hmac, "hello", 5) != CRYPT_OK) { |
|
|
1453 printf("Error processing hmac: %s\n", error_to_string(err)); |
|
3
|
1454 return -1; |
|
|
1455 } |
|
|
1456 |
|
|
1457 /* get result (presumably to use it somehow...) */ |
|
|
1458 dstlen = sizeof(dst); |
|
15
|
1459 if ((err = hmac_done(&hmac, dst, &dstlen)) != CRYPT_OK) { |
|
|
1460 printf("Error finishing hmac: %s\n", error_to_string(err)); |
|
3
|
1461 return -1; |
|
|
1462 } |
|
|
1463 printf("The hmac is %lu bytes long\n", dstlen); |
|
|
1464 |
|
|
1465 /* return */ |
|
|
1466 return 0; |
|
|
1467 } |
|
|
1468 \end{verbatim} |
|
|
1469 \end{small} |
|
|
1470 |
|
|
1471 \section{OMAC Support} |
|
|
1472 OMAC\footnote{\url{http://crypt.cis.ibaraki.ac.jp/omac/omac.html}}, which stands for \textit{One-Key CBC MAC} is an |
|
|
1473 algorithm which produces a Message Authentication Code (MAC) using only a block cipher such as AES. From an API |
|
|
1474 standpoint the OMAC routines work much like the HMAC routines do. Instead in this case a cipher is used instead of a hash. |
|
|
1475 |
|
|
1476 To start an OMAC state you call |
|
15
|
1477 \index{omac\_init()} |
|
3
|
1478 \begin{verbatim} |
|
|
1479 int omac_init(omac_state *omac, int cipher, |
|
|
1480 const unsigned char *key, unsigned long keylen); |
|
|
1481 \end{verbatim} |
|
|
1482 The ``omac'' variable is the state for the OMAC algorithm. ``cipher'' is the index into the cipher\_descriptor table |
|
|
1483 of the cipher\footnote{The cipher must have a 64 or 128 bit block size. Such as CAST5, Blowfish, DES, AES, Twofish, etc.} you |
|
|
1484 wish to use. ``key'' and ``keylen'' are the keys used to authenticate the data. |
|
|
1485 |
|
|
1486 To send data through the algorithm call |
|
15
|
1487 \index{omac\_process()} |
|
3
|
1488 \begin{verbatim} |
|
|
1489 int omac_process(omac_state *state, |
|
|
1490 const unsigned char *buf, unsigned long len); |
|
|
1491 \end{verbatim} |
|
|
1492 This will send ``len'' bytes from ``buf'' through the active OMAC state ``state''. Returns \textbf{CRYPT\_OK} if the |
|
|
1493 function succeeds. The function is not sensitive to the granularity of the data. For example, |
|
|
1494 |
|
|
1495 \begin{verbatim} |
|
|
1496 omac_process(&mystate, "hello", 5); |
|
|
1497 omac_process(&mystate, " world", 6); |
|
|
1498 \end{verbatim} |
|
|
1499 |
|
|
1500 Would produce the same result as, |
|
|
1501 |
|
|
1502 \begin{verbatim} |
|
|
1503 omac_process(&mystate, "hello world", 11); |
|
|
1504 \end{verbatim} |
|
|
1505 |
|
|
1506 When you are done processing the message you can call the following to compute the message tag. |
|
|
1507 |
|
15
|
1508 \index{omac\_done()} |
|
3
|
1509 \begin{verbatim} |
|
|
1510 int omac_done(omac_state *state, |
|
|
1511 unsigned char *out, unsigned long *outlen); |
|
|
1512 \end{verbatim} |
|
|
1513 Which will terminate the OMAC and output the \textit{tag} (MAC) to ``out''. Note that unlike the HMAC and other code |
|
|
1514 ``outlen'' can be smaller than the default MAC size (for instance AES would make a 16-byte tag). Part of the OMAC |
|
|
1515 specification states that the output may be truncated. So if you pass in $outlen = 5$ and use AES as your cipher than |
|
|
1516 the output MAC code will only be five bytes long. If ``outlen'' is larger than the default size it is set to the default |
|
|
1517 size to show how many bytes were actually used. |
|
|
1518 |
|
|
1519 Similar to the HMAC code the file and memory functions are also provided. To OMAC a buffer of memory in one shot use the |
|
|
1520 following function. |
|
|
1521 |
|
15
|
1522 \index{omac\_memory()} |
|
3
|
1523 \begin{verbatim} |
|
|
1524 int omac_memory(int cipher, |
|
|
1525 const unsigned char *key, unsigned long keylen, |
|
|
1526 const unsigned char *msg, unsigned long msglen, |
|
|
1527 unsigned char *out, unsigned long *outlen); |
|
|
1528 \end{verbatim} |
|
|
1529 This will compute the OMAC of ``msglen'' bytes of ``msg'' using the key ``key'' of length ``keylen'' bytes and the cipher |
|
|
1530 specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with the same |
|
|
1531 rules as omac\_done. |
|
|
1532 |
|
|
1533 To OMAC a file use |
|
15
|
1534 \index{omac\_file()} |
|
3
|
1535 \begin{verbatim} |
|
|
1536 int omac_file(int cipher, |
|
|
1537 const unsigned char *key, unsigned long keylen, |
|
|
1538 const char *filename, |
|
|
1539 unsigned char *out, unsigned long *outlen); |
|
|
1540 \end{verbatim} |
|
|
1541 |
|
|
1542 Which will OMAC the entire contents of the file specified by ``filename'' using the key ``key'' of length ``keylen'' bytes |
|
|
1543 and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with |
|
|
1544 the same rules as omac\_done. |
|
|
1545 |
|
|
1546 To test if the OMAC code is working there is the following function: |
|
15
|
1547 \index{omac\_test()} |
|
3
|
1548 \begin{verbatim} |
|
|
1549 int omac_test(void); |
|
|
1550 \end{verbatim} |
|
|
1551 Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. Some example code for using the |
|
|
1552 OMAC system is given below. |
|
|
1553 |
|
|
1554 \begin{small} |
|
|
1555 \begin{verbatim} |
|
|
1556 #include <mycrypt.h> |
|
|
1557 int main(void) |
|
|
1558 { |
|
|
1559 int idx, err; |
|
|
1560 omac_state omac; |
|
|
1561 unsigned char key[16], dst[MAXBLOCKSIZE]; |
|
|
1562 unsigned long dstlen; |
|
|
1563 |
|
|
1564 /* register Rijndael */ |
|
|
1565 if (register_cipher(&rijndael_desc) == -1) { |
|
|
1566 printf("Error registering Rijndael\n"); |
|
|
1567 return -1; |
|
|
1568 } |
|
|
1569 |
|
|
1570 /* get index of Rijndael in cipher descriptor table */ |
|
|
1571 idx = find_cipher("rijndael"); |
|
|
1572 |
|
|
1573 /* we would make up our symmetric key in "key[]" here */ |
|
|
1574 |
|
|
1575 /* start the OMAC */ |
|
|
1576 if ((err = omac_init(&omac, idx, key, 16)) != CRYPT_OK) { |
|
|
1577 printf("Error setting up omac: %s\n", error_to_string(err)); |
|
|
1578 return -1; |
|
|
1579 } |
|
|
1580 |
|
|
1581 /* process a few octets */ |
|
|
1582 if((err = omac_process(&omac, "hello", 5) != CRYPT_OK) { |
|
|
1583 printf("Error processing omac: %s\n", error_to_string(err)); |
|
|
1584 return -1; |
|
|
1585 } |
|
|
1586 |
|
|
1587 /* get result (presumably to use it somehow...) */ |
|
|
1588 dstlen = sizeof(dst); |
|
|
1589 if ((err = omac_done(&omac, dst, &dstlen)) != CRYPT_OK) { |
|
|
1590 printf("Error finishing omac: %s\n", error_to_string(err)); |
|
|
1591 return -1; |
|
|
1592 } |
|
|
1593 printf("The omac is %lu bytes long\n", dstlen); |
|
|
1594 |
|
|
1595 /* return */ |
|
|
1596 return 0; |
|
|
1597 } |
|
|
1598 \end{verbatim} |
|
|
1599 \end{small} |
|
|
1600 |
|
|
1601 \section{PMAC Support} |
|
|
1602 The PMAC\footnote{J.Black, P.Rogaway, ``A Block--Cipher Mode of Operation for Parallelizable Message Authentication''} |
|
|
1603 protocol is another MAC algorithm that relies solely on a symmetric-key block cipher. It uses essentially the same |
|
|
1604 API as the provided OMAC code. |
|
|
1605 |
|
|
1606 A PMAC state is initialized with the following. |
|
|
1607 |
|
15
|
1608 \index{pmac\_init()} |
|
3
|
1609 \begin{verbatim} |
|
|
1610 int pmac_init(pmac_state *pmac, int cipher, |
|
|
1611 const unsigned char *key, unsigned long keylen); |
|
|
1612 \end{verbatim} |
|
|
1613 Which initializes the ``pmac'' state with the given ``cipher'' and ``key'' of length ``keylen'' bytes. The chosen cipher |
|
|
1614 must have a 64 or 128 bit block size (e.x. AES). |
|
|
1615 |
|
|
1616 To MAC data simply send it through the process function. |
|
|
1617 |
|
15
|
1618 \index{pmac\_process()} |
|
3
|
1619 \begin{verbatim} |
|
|
1620 int pmac_process(pmac_state *state, |
|
|
1621 const unsigned char *buf, unsigned long len); |
|
|
1622 \end{verbatim} |
|
|
1623 This will process ``len'' bytes of ``buf'' in the given ``state''. The function is not sensitive to the granularity of the |
|
|
1624 data. For example, |
|
|
1625 |
|
|
1626 \begin{verbatim} |
|
|
1627 pmac_process(&mystate, "hello", 5); |
|
|
1628 pmac_process(&mystate, " world", 6); |
|
|
1629 \end{verbatim} |
|
|
1630 |
|
|
1631 Would produce the same result as, |
|
|
1632 |
|
|
1633 \begin{verbatim} |
|
|
1634 pmac_process(&mystate, "hello world", 11); |
|
|
1635 \end{verbatim} |
|
|
1636 |
|
|
1637 When a complete message has been processed the following function can be called to compute the message tag. |
|
|
1638 |
|
15
|
1639 \index{pmac\_done()} |
|
3
|
1640 \begin{verbatim} |
|
|
1641 int pmac_done(pmac_state *state, |
|
|
1642 unsigned char *out, unsigned long *outlen); |
|
|
1643 \end{verbatim} |
|
|
1644 This will store upto ``outlen'' bytes of the tag for the given ``state'' into ``out''. Note that if ``outlen'' is larger |
|
|
1645 than the size of the tag it is set to the amount of bytes stored in ``out''. |
|
|
1646 |
|
|
1647 Similar to the PMAC code the file and memory functions are also provided. To PMAC a buffer of memory in one shot use the |
|
|
1648 following function. |
|
|
1649 |
|
15
|
1650 \index{pmac\_memory()} |
|
3
|
1651 \begin{verbatim} |
|
|
1652 int pmac_memory(int cipher, |
|
|
1653 const unsigned char *key, unsigned long keylen, |
|
|
1654 const unsigned char *msg, unsigned long msglen, |
|
|
1655 unsigned char *out, unsigned long *outlen); |
|
|
1656 \end{verbatim} |
|
|
1657 This will compute the PMAC of ``msglen'' bytes of ``msg'' using the key ``key'' of length ``keylen'' bytes and the cipher |
|
|
1658 specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with the same |
|
|
1659 rules as omac\_done. |
|
|
1660 |
|
|
1661 To PMAC a file use |
|
15
|
1662 \index{pmac\_file()} |
|
3
|
1663 \begin{verbatim} |
|
|
1664 int pmac_file(int cipher, |
|
|
1665 const unsigned char *key, unsigned long keylen, |
|
|
1666 const char *filename, |
|
|
1667 unsigned char *out, unsigned long *outlen); |
|
|
1668 \end{verbatim} |
|
|
1669 |
|
|
1670 Which will PMAC the entire contents of the file specified by ``filename'' using the key ``key'' of length ``keylen'' bytes |
|
|
1671 and the cipher specified by the ``cipher'''th entry in the cipher\_descriptor table. It will store the MAC in ``out'' with |
|
|
1672 the same rules as omac\_done. |
|
|
1673 |
|
|
1674 To test if the PMAC code is working there is the following function: |
|
|
1675 \begin{verbatim} |
|
|
1676 int pmac_test(void); |
|
|
1677 \end{verbatim} |
|
|
1678 Which returns {\bf CRYPT\_OK} if the code passes otherwise it returns an error code. |
|
|
1679 |
|
|
1680 |
|
|
1681 \chapter{Pseudo-Random Number Generators} |
|
|
1682 \section{Core Functions} |
|
|
1683 |
|
|
1684 The library provides an array of core functions for Pseudo-Random Number Generators (PRNGs) as well. A cryptographic PRNG is |
|
|
1685 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) |
|
|
1686 key generation. There is a universal structure called ``prng\_state''. To initialize a PRNG call: |
|
|
1687 \begin{verbatim} |
|
|
1688 int XXX_start(prng_state *prng); |
|
|
1689 \end{verbatim} |
|
|
1690 |
|
|
1691 This will setup the PRNG for future use and not seed it. In order |
|
|
1692 for the PRNG to be cryptographically useful you must give it entropy. Ideally you'd have some OS level source to tap |
|
|
1693 like in UNIX (see section 5.3). To add entropy to the PRNG call: |
|
|
1694 \begin{verbatim} |
|
|
1695 int XXX_add_entropy(const unsigned char *in, unsigned long len, |
|
|
1696 prng_state *prng); |
|
|
1697 \end{verbatim} |
|
|
1698 |
|
|
1699 Which returns {\bf CRYPTO\_OK} if the entropy was accepted. Once you think you have enough entropy you call another |
|
|
1700 function to put the entropy into action. |
|
|
1701 \begin{verbatim} |
|
|
1702 int XXX_ready(prng_state *prng); |
|
|
1703 \end{verbatim} |
|
|
1704 |
|
|
1705 Which returns {\bf CRYPTO\_OK} if it is ready. Finally to actually read bytes call: |
|
|
1706 \begin{verbatim} |
|
|
1707 unsigned long XXX_read(unsigned char *out, unsigned long len, |
|
|
1708 prng_state *prng); |
|
|
1709 \end{verbatim} |
|
|
1710 |
|
|
1711 Which returns the number of bytes read from the PRNG. |
|
|
1712 |
|
|
1713 \subsection{Remarks} |
|
|
1714 |
|
|
1715 It is possible to be adding entropy and reading from a PRNG at the same time. For example, if you first seed the PRNG |
|
|
1716 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 |
|
|
1717 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 |
|
|
1718 checking is guaranteed to see if the entropy is sufficient or if the PRNG is even in a ready state before reading. |
|
|
1719 |
|
|
1720 \subsection{Example} |
|
|
1721 |
|
|
1722 Below is a simple snippet to read 10 bytes from yarrow. Its important to note that this snippet is {\bf NOT} secure since |
|
|
1723 the entropy added is not random. |
|
|
1724 |
|
|
1725 \begin{verbatim} |
|
|
1726 #include <mycrypt.h> |
|
|
1727 int main(void) |
|
|
1728 { |
|
|
1729 prng_state prng; |
|
|
1730 unsigned char buf[10]; |
|
|
1731 int err; |
|
|
1732 |
|
|
1733 /* start it */ |
|
|
1734 if ((err = yarrow_start(&prng)) != CRYPT_OK) { |
|
|
1735 printf("Start error: %s\n", error_to_string(err)); |
|
|
1736 } |
|
|
1737 /* add entropy */ |
|
|
1738 if ((err = yarrow_add_entropy("hello world", 11, &prng)) != CRYPT_OK) { |
|
|
1739 printf("Add_entropy error: %s\n", error_to_string(err)); |
|
|
1740 } |
|
|
1741 /* ready and read */ |
|
|
1742 if ((err = yarrow_ready(&prng)) != CRYPT_OK) { |
|
|
1743 printf("Ready error: %s\n", error_to_string(err)); |
|
|
1744 } |
|
|
1745 printf("Read %lu bytes from yarrow\n", yarrow_read(buf, 10, &prng)); |
|
|
1746 return 0; |
|
|
1747 } |
|
|
1748 \end{verbatim} |
|
|
1749 |
|
|
1750 \section{PRNG Descriptors} |
|
|
1751 \index{PRNG Descriptor} |
|
|
1752 PRNGs have descriptors too (surprised?). Stored in the structure ``prng\_descriptor''. The format of an element is: |
|
|
1753 \begin{verbatim} |
|
|
1754 struct _prng_descriptor { |
|
|
1755 char *name; |
|
|
1756 int (*start) (prng_state *); |
|
|
1757 int (*add_entropy)(const unsigned char *, unsigned long, prng_state *); |
|
|
1758 int (*ready) (prng_state *); |
|
|
1759 unsigned long (*read)(unsigned char *, unsigned long len, prng_state *); |
|
|
1760 }; |
|
|
1761 \end{verbatim} |
|
|
1762 |
|
|
1763 There is a ``int find\_prng(char *name)'' function as well. Returns -1 if the PRNG is not found, otherwise it returns |
|
|
1764 the position in the prng\_descriptor array. |
|
|
1765 |
|
|
1766 Just like the ciphers and hashes you must register your prng before you can use it. The two functions provided work |
|
|
1767 exactly as those for the cipher registry functions. They are: |
|
|
1768 \begin{verbatim} |
|
|
1769 int register_prng(const struct _prng_descriptor *prng); |
|
|
1770 int unregister_prng(const struct _prng_descriptor *prng); |
|
|
1771 \end{verbatim} |
|
|
1772 |
|
|
1773 \subsubsection{PRNGs Provided} |
|
|
1774 Currently Yarrow (yarrow\_desc), RC4 (rc4\_desc) and the secure RNG (sprng\_desc) are provided as PRNGs within the |
|
|
1775 library. |
|
|
1776 |
|
|
1777 RC4 is provided with a PRNG interface because it is a stream cipher and not well suited for the symmetric block cipher |
|
|
1778 interface. You provide the key for RC4 via the rc4\_add\_entropy() function. By calling rc4\_ready() the key will be used |
|
|
1779 to setup the RC4 state for encryption or decryption. The rc4\_read() function has been modified from RC4 since it will |
|
|
1780 XOR the output of the RC4 keystream generator against the input buffer you provide. The following snippet will demonstrate |
|
|
1781 how to encrypt a buffer with RC4: |
|
|
1782 |
|
|
1783 \begin{small} |
|
|
1784 \begin{verbatim} |
|
|
1785 #include <mycrypt.h> |
|
|
1786 int main(void) |
|
|
1787 { |
|
|
1788 prng_state prng; |
|
|
1789 unsigned char buf[32]; |
|
|
1790 int err; |
|
|
1791 |
|
|
1792 if ((err = rc4_start(&prng)) != CRYPT_OK) { |
|
|
1793 printf("RC4 init error: %s\n", error_to_string(err)); |
|
|
1794 exit(-1); |
|
|
1795 } |
|
|
1796 |
|
|
1797 /* use ``key'' as the key */ |
|
|
1798 if ((err = rc4_add_entropy("key", 3, &prng)) != CRYPT_OK) { |
|
|
1799 printf("RC4 add entropy error: %s\n", error_to_string(err)); |
|
|
1800 exit(-1); |
|
|
1801 } |
|
|
1802 |
|
|
1803 /* setup RC4 for use */ |
|
|
1804 if ((err = rc4_ready(&prng)) != CRYPT_OK) { |
|
|
1805 printf("RC4 ready error: %s\n", error_to_string(err)); |
|
|
1806 exit(-1); |
|
|
1807 } |
|
|
1808 |
|
|
1809 /* encrypt buffer */ |
|
|
1810 strcpy(buf,"hello world"); |
|
|
1811 if (rc4_read(buf, 11, &prng) != 11) { |
|
|
1812 printf("RC4 read error\n"); |
|
|
1813 exit(-1); |
|
|
1814 } |
|
|
1815 return 0; |
|
|
1816 } |
|
|
1817 \end{verbatim} |
|
|
1818 \end{small} |
|
|
1819 To decrypt you have to do the exact same steps. |
|
|
1820 |
|
|
1821 \section{The Secure RNG} |
|
|
1822 \index{Secure RNG} |
|
|
1823 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 |
|
|
1824 by performing some computation on fresh input bits. Possibly the hardest thing to get correctly in a cryptosystem is the |
|
|
1825 PRNG. Computers are deterministic beasts that try hard not to stray from pre-determined paths. That makes gathering |
|
|
1826 entropy needed to seed the PRNG a hard task. |
|
|
1827 |
|
|
1828 There is one small function that may help on certain platforms: |
|
|
1829 \index{rng\_get\_bytes()} |
|
|
1830 \begin{verbatim} |
|
|
1831 unsigned long rng_get_bytes(unsigned char *buf, unsigned long len, |
|
|
1832 void (*callback)(void)); |
|
|
1833 \end{verbatim} |
|
|
1834 |
|
|
1835 Which will try one of three methods of getting random data. The first is to open the popular ``/dev/random'' device which |
|
|
1836 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.}. |
|
|
1837 The second method is to try the Microsoft Cryptographic Service Provider and read the RNG. The third method is an ANSI C |
|
|
1838 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 |
|
|
1839 used so the calling application can still work. This is useful since the ANSI C RNG has a throughput of three |
|
|
1840 bytes a second. The callback pointer may be set to {\bf NULL} to avoid using it if you don't want to. The function |
|
|
1841 returns the number of bytes actually read from any RNG source. There is a function to help setup a PRNG as well: |
|
|
1842 \index{rng\_make\_prng()} |
|
|
1843 \begin{verbatim} |
|
|
1844 int rng_make_prng(int bits, int wprng, prng_state *prng, |
|
|
1845 void (*callback)(void)); |
|
|
1846 \end{verbatim} |
|
|
1847 This will try to setup the prng with a state of at least ``bits'' of entropy. The ``callback'' parameter works much like |
|
|
1848 the callback in ``rng\_get\_bytes()''. It is highly recommended that you use this function to setup your PRNGs unless you have a |
|
|
1849 platform where the RNG doesn't work well. Example usage of this function is given below. |
|
|
1850 |
|
|
1851 \begin{small} |
|
|
1852 \begin{verbatim} |
|
|
1853 #include <mycrypt.h> |
|
|
1854 int main(void) |
|
|
1855 { |
|
|
1856 ecc_key mykey; |
|
|
1857 prng_state prng; |
|
|
1858 int err; |
|
|
1859 |
|
|
1860 /* register yarrow */ |
|
|
1861 if (register_prng(&yarrow_desc) == -1) { |
|
|
1862 printf("Error registering Yarrow\n"); |
|
|
1863 return -1; |
|
|
1864 } |
|
|
1865 |
|
|
1866 /* setup the PRNG */ |
|
|
1867 if ((err = rng_make_prng(128, find_prng("yarrow"), &prng, NULL)) != CRYPT_OK) { |
|
|
1868 printf("Error setting up PRNG, %s\n", error_to_string(err)); |
|
|
1869 return -1; |
|
|
1870 } |
|
|
1871 |
|
|
1872 /* make a 192-bit ECC key */ |
|
|
1873 if ((err = ecc_make_key(&prng, find_prng("yarrow"), 24, &mykey)) != CRYPT_OK) { |
|
|
1874 printf("Error making key: %s\n", error_to_string(err)); |
|
|
1875 return -1; |
|
|
1876 } |
|
|
1877 return 0; |
|
|
1878 } |
|
|
1879 \end{verbatim} |
|
|
1880 \end{small} |
|
|
1881 |
|
|
1882 \subsection{The Secure PRNG Interface} |
|
|
1883 It is possible to access the secure RNG through the PRNG interface and in turn use it within dependent functions such |
|
|
1884 as the PK API. This simplifies the cryptosystem on platforms where the secure RNG is fast. The secure PRNG never |
|
|
1885 requires to be started, that is you need not call the start, add\_entropy or ready functions. For example, consider |
|
|
1886 the previous example using this PRNG. |
|
|
1887 |
|
|
1888 \begin{small} |
|
|
1889 \begin{verbatim} |
|
|
1890 #include <mycrypt.h> |
|
|
1891 int main(void) |
|
|
1892 { |
|
|
1893 ecc_key mykey; |
|
|
1894 int err; |
|
|
1895 |
|
|
1896 /* register SPRNG */ |
|
|
1897 if (register_prng(&sprng_desc) == -1) { |
|
|
1898 printf("Error registering SPRNG\n"); |
|
|
1899 return -1; |
|
|
1900 } |
|
|
1901 |
|
|
1902 /* make a 192-bit ECC key */ |
|
|
1903 if ((err = ecc_make_key(NULL, find_prng("sprng"), 24, &mykey)) != CRYPT_OK) { |
|
|
1904 printf("Error making key: %s\n", error_to_string(err)); |
|
|
1905 return -1; |
|
|
1906 } |
|
|
1907 return 0; |
|
|
1908 } |
|
|
1909 \end{verbatim} |
|
|
1910 \end{small} |
|
|
1911 |
|
|
1912 \chapter{RSA Public Key Cryptography} |
|
15
|
1913 |
|
|
1914 \section{Introduction} |
|
|
1915 RSA wrote the PKCS \#1 specifications which detail RSA Public Key Cryptography. In the specifications are |
|
|
1916 padding algorithms for encryption and signatures. The standard includes ``v1.5'' and ``v2.0'' algorithms. |
|
|
1917 To simplify matters a little the v2.0 encryption and signature padding algorithms are called OAEP and PSS |
|
|
1918 respectively. |
|
3
|
1919 |
|
|
1920 \section{PKCS \#1 Encryption} |
|
|
1921 |
|
|
1922 PKCS \#1 RSA Encryption amounts to OAEP padding of the input message followed by the modular exponentiation. As far as this portion of |
|
|
1923 the library is concerned we are only dealing with th OAEP padding of the message. |
|
|
1924 |
|
|
1925 \subsection{OAEP Encoding} |
|
|
1926 |
|
15
|
1927 \index{pkcs\_1\_oaep\_encode()} |
|
3
|
1928 \begin{alltt} |
|
|
1929 int pkcs_1_oaep_encode(const unsigned char *msg, unsigned long msglen, |
|
|
1930 const unsigned char *lparam, unsigned long lparamlen, |
|
15
|
1931 unsigned long modulus_bitlen, prng_state *prng, |
|
|
1932 int prng_idx, int hash_idx, |
|
3
|
1933 unsigned char *out, unsigned long *outlen); |
|
|
1934 \end{alltt} |
|
|
1935 |
|
|
1936 This accepts ``msg'' as input of length ``msglen'' which will be OAEP padded. The ``lparam'' variable is an additional system specific |
|
|
1937 tag that can be applied to the encoding. This is useful to identify which system encoded the message. If no variance is desired then |
|
|
1938 ``lparam'' can be set to \textbf{NULL}. |
|
|
1939 |
|
|
1940 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 |
|
|
1941 ``modulus\_bitlen''. ``hash\_idx'' is the index into the hash descriptor table of the hash desired. PKCS \#1 allows any hash to be |
|
|
1942 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 |
|
|
1943 sized input message. ``prng\_idx'' and ``prng'' are the random number generator arguments required to randomize the padding process. |
|
|
1944 The padded message is stored in ``out'' along with the length in ``outlen''. |
|
|
1945 |
|
|
1946 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 |
|
|
1947 $m - 2h - 2$. For example, with a $1024$--bit RSA key and SHA--1 as the hash the maximum payload is $86$ bytes. |
|
|
1948 |
|
|
1949 Note that when the message is padded it still has not been RSA encrypted. You must pass the output of this function to |
|
|
1950 rsa\_exptmod() to encrypt it. |
|
|
1951 |
|
|
1952 \subsection{OAEP Decoding} |
|
|
1953 |
|
15
|
1954 \index{pkcs\_1\_oaep\_decode()} |
|
3
|
1955 \begin{alltt} |
|
|
1956 int pkcs_1_oaep_decode(const unsigned char *msg, unsigned long msglen, |
|
|
1957 const unsigned char *lparam, unsigned long lparamlen, |
|
|
1958 unsigned long modulus_bitlen, int hash_idx, |
|
15
|
1959 unsigned char *out, unsigned long *outlen, |
|
|
1960 int *res); |
|
3
|
1961 \end{alltt} |
|
|
1962 |
|
|
1963 This function decodes an OAEP encoded message and outputs the original message that was passed to the OAEP encoder. ``msg'' is the |
|
|
1964 output of pkcs\_1\_oaep\_encode() of length ``msglen''. ``lparam'' is the same system variable passed to the OAEP encoder. If it does not |
|
|
1965 match what was used during encoding this function will not decode the packet. ``modulus\_bitlen'' is the size of the RSA modulus in bits |
|
|
1966 and must match what was used during encoding. Similarly the ``hash\_idx'' index into the hash descriptor table must match what was used |
|
|
1967 during encoding. |
|
|
1968 |
|
15
|
1969 If the function succeeds it decodes the OAEP encoded message into ``out'' of length ``outlen'' and stores a |
|
|
1970 $1$ in ``res''. If the packet is invalid it stores $0$ in ``res'' and if the function fails for another reason |
|
|
1971 it returns an error code. |
|
|
1972 |
|
|
1973 \subsection{PKCS \#1 v1.5 Encoding} |
|
|
1974 |
|
|
1975 \index{pkcs\_1\_v15\_es\_encode()} |
|
|
1976 \begin{verbatim} |
|
|
1977 int pkcs_1_v15_es_encode(const unsigned char *msg, unsigned long msglen, |
|
|
1978 unsigned long modulus_bitlen, |
|
|
1979 prng_state *prng, int prng_idx, |
|
|
1980 unsigned char *out, unsigned long *outlen); |
|
|
1981 \end{verbatim} |
|
|
1982 |
|
|
1983 This will PKCS v1.5 encode the data in ``msg'' of length ``msglen''. Pass the length (in bits) of your |
|
|
1984 RSA modulus in ``modulus\_bitlen''. The encoded data will be stored in ``out'' of length ``outlen''. |
|
|
1985 |
|
|
1986 \subsection{PKCS \#1 v1.5 Decoding} |
|
|
1987 \index{pkcs\_1\_v15\_es\_decode()} |
|
|
1988 \begin{verbatim} |
|
|
1989 int pkcs_1_v15_es_decode(const unsigned char *msg, unsigned long msglen, |
|
|
1990 unsigned long modulus_bitlen, |
|
|
1991 unsigned char *out, unsigned long outlen, |
|
|
1992 int *res); |
|
|
1993 \end{verbatim} |
|
|
1994 |
|
|
1995 This will PKCS v1.5 decode the message in ``msg'' of length ``msglen''. It will store the output in ``out''. Note |
|
|
1996 that the length of the output ``outlen'' is a constant. This decoder cannot determine the original message |
|
|
1997 length. If the data in ``msg'' is a valid packet then a $1$ is stored in ``res'', otherwise a $0$ is |
|
|
1998 stored. |
|
3
|
1999 |
|
|
2000 \section{PKCS \#1 Digital Signatures} |
|
|
2001 |
|
|
2002 \subsection{PSS Encoding} |
|
|
2003 PSS encoding is the second half of the PKCS \#1 standard which is padding to be applied to messages that are signed. |
|
|
2004 |
|
15
|
2005 \index{pkcs\_1\_pss\_encode()} |
|
3
|
2006 \begin{alltt} |
|
|
2007 int pkcs_1_pss_encode(const unsigned char *msghash, unsigned long msghashlen, |
|
15
|
2008 unsigned long saltlen, prng_state *prng, |
|
|
2009 int prng_idx, int hash_idx, |
|
3
|
2010 unsigned long modulus_bitlen, |
|
|
2011 unsigned char *out, unsigned long *outlen); |
|
|
2012 \end{alltt} |
|
|
2013 |
|
|
2014 This function assumes the message to be PSS encoded has previously been hashed. The input hash ``msghash'' is of length |
|
|
2015 ``msghashlen''. PSS allows a variable length random salt (it can be zero length) to be introduced in the signature process. |
|
|
2016 ``hash\_idx'' is the index into the hash descriptor table of the hash to use. ``prng\_idx'' and ``prng'' are the random |
|
|
2017 number generator information required for the salt. |
|
|
2018 |
|
15
|
2019 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 |
|
3
|
2020 of the modulus $h$ the length of the hash output (in octets) then there can be $m - h - 2$ bytes of salt. |
|
|
2021 |
|
|
2022 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(). |
|
|
2023 |
|
|
2024 \subsection{PSS Decoding} |
|
|
2025 |
|
|
2026 To decode a PSS encoded signature block you have to use the following. |
|
|
2027 |
|
15
|
2028 \index{pkcs\_1\_pss\_decode()} |
|
3
|
2029 \begin{alltt} |
|
|
2030 int pkcs_1_pss_decode(const unsigned char *msghash, unsigned long msghashlen, |
|
|
2031 const unsigned char *sig, unsigned long siglen, |
|
|
2032 unsigned long saltlen, int hash_idx, |
|
|
2033 unsigned long modulus_bitlen, int *res); |
|
|
2034 \end{alltt} |
|
|
2035 This will decode the PSS encoded message in ``sig'' of length ``siglen'' and compare it to values in ``msghash'' of length |
|
|
2036 ``msghashlen''. If the block is a valid PSS block and the decoded hash equals the hash supplied ``res'' is set to non--zero. Otherwise, |
|
|
2037 it is set to zero. The rest of the parameters are as in the PSS encode call. |
|
|
2038 |
|
|
2039 It's important to use the same ``saltlen'' and hash for both encoding and decoding as otherwise the procedure will not work. |
|
|
2040 |
|
15
|
2041 \subsection{PKCS \#1 v1.5 Encoding} |
|
|
2042 |
|
|
2043 \index{pkcs\_1\_v15\_sa\_encode()} |
|
|
2044 \begin{verbatim} |
|
|
2045 int pkcs_1_v15_sa_encode(const unsigned char *msghash, unsigned long msghashlen, |
|
|
2046 int hash_idx, unsigned long modulus_bitlen, |
|
|
2047 unsigned char *out, unsigned long *outlen); |
|
|
2048 \end{verbatim} |
|
|
2049 |
|
|
2050 This will PKCS \#1 v1.5 signature encode the message hash ``msghash'' of length ``msghashlen''. You have |
|
|
2051 to tell this routine which hash produced the message hash in ``hash\_idx''. The encoded hash is stored |
|
|
2052 in ``out'' of length ``outlen''. |
|
|
2053 |
|
|
2054 \subsection{PKCS \#1 v1.5 Decoding} |
|
|
2055 |
|
|
2056 \index{pkcs\_1\_v15\_sa\_decode()} |
|
|
2057 \begin{verbatim} |
|
|
2058 int pkcs_1_v15_sa_decode(const unsigned char *msghash, unsigned long msghashlen, |
|
|
2059 const unsigned char *sig, unsigned long siglen, |
|
|
2060 int hash_idx, unsigned long modulus_bitlen, |
|
|
2061 int *res); |
|
|
2062 \end{verbatim} |
|
|
2063 |
|
|
2064 This will PKCS \#1 v1.5 signature decode the data in ``sig'' of length ``siglen'' and compare the extracted |
|
|
2065 hash against ``msghash'' of length ``msghashlen''. You have to tell this routine which hash produced the |
|
|
2066 message digest in ``hash\_idx''. If the packet is valid and the hashes match ``res'' is set to $1$. Otherwise, |
|
|
2067 it is set to $0$. |
|
|
2068 |
|
|
2069 \section{RSA Operations} |
|
|
2070 \subsection{Background} |
|
|
2071 |
|
|
2072 RSA is a public key algorithm that is based on the inability to find the ``e-th'' root modulo a composite of unknown |
|
|
2073 factorization. Normally the difficulty of breaking RSA is associated with the integer factoring problem but they are |
|
|
2074 not strictly equivalent. |
|
|
2075 |
|
|
2076 The system begins with with two primes $p$ and $q$ and their product $N = pq$. The order or ``Euler totient'' of the |
|
|
2077 multiplicative sub-group formed modulo $N$ is given as $\phi(N) = (p - 1)(q - 1)$ which can be reduced to |
|
|
2078 $\mbox{lcm}(p - 1, q - 1)$. The public key consists of the composite $N$ and some integer $e$ such that |
|
|
2079 $\mbox{gcd}(e, \phi(N)) = 1$. The private key consists of the composite $N$ and the inverse of $e$ modulo $\phi(N)$ |
|
|
2080 often simply denoted as $de \equiv 1\mbox{ }(\mbox{mod }\phi(N))$. |
|
|
2081 |
|
|
2082 A person who wants to encrypt with your public key simply forms an integer (the plaintext) $M$ such that |
|
|
2083 $1 < M < N-2$ and computes the ciphertext $C = M^e\mbox{ }(\mbox{mod }N)$. Since finding the inverse exponent $d$ |
|
|
2084 given only $N$ and $e$ appears to be intractable only the owner of the private key can decrypt the ciphertext and compute |
|
|
2085 $C^d \equiv \left (M^e \right)^d \equiv M^1 \equiv M\mbox{ }(\mbox{mod }N)$. Similarly the owner of the private key |
|
|
2086 can sign a message by ``decrypting'' it. Others can verify it by ``encrypting'' it. |
|
|
2087 |
|
|
2088 Currently RSA is a difficult system to cryptanalyze provided that both primes are large and not close to each other. |
|
|
2089 Ideally $e$ should be larger than $100$ to prevent direct analysis. For example, if $e$ is three and you do not pad |
|
|
2090 the plaintext to be encrypted than it is possible that $M^3 < N$ in which case finding the cube-root would be trivial. |
|
|
2091 The most often suggested value for $e$ is $65537$ since it is large enough to make such attacks impossible and also well |
|
|
2092 designed for fast exponentiation (requires 16 squarings and one multiplication). |
|
|
2093 |
|
|
2094 It is important to pad the input to RSA since it has particular mathematical structure. For instance |
|
|
2095 $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 |
|
|
2096 to have a forged signature for. Simply get the signatures for $M_1$ and $M_2$ on their own and multiply the result |
|
|
2097 together. Similar tricks can be used to deduce plaintexts from ciphertexts. It is important not only to sign |
|
|
2098 the hash of documents only but also to pad the inputs with data to remove such structure. |
|
|
2099 |
|
|
2100 \subsection{RSA Key Generation} |
|
|
2101 |
|
|
2102 For RSA routines a single ``rsa\_key'' structure is used. To make a new RSA key call: |
|
|
2103 \index{rsa\_make\_key()} |
|
|
2104 \begin{verbatim} |
|
|
2105 int rsa_make_key(prng_state *prng, |
|
|
2106 int wprng, int size, |
|
|
2107 long e, rsa_key *key); |
|
|
2108 \end{verbatim} |
|
|
2109 |
|
|
2110 Where ``wprng'' is the index into the PRNG descriptor array. ``size'' is the size in bytes of the RSA modulus desired. |
|
|
2111 ``e'' is the encryption exponent desired, typical values are 3, 17, 257 and 65537. I suggest you stick with 65537 since its big |
|
|
2112 enough to prevent trivial math attacks and not super slow. ``key'' is where the key is placed. All keys must be at |
|
|
2113 least 128 bytes and no more than 512 bytes in size (\textit{that is from 1024 to 4096 bits}). |
|
|
2114 |
|
|
2115 Note that the ``rsa\_make\_key()'' function allocates memory at runtime when you make the key. Make sure to call |
|
|
2116 ``rsa\_free()'' (see below) when you are finished with the key. If ``rsa\_make\_key()'' fails it will automatically |
|
|
2117 free the ram allocated itself. |
|
|
2118 |
|
|
2119 There are three types of RSA keys. The types are {\bf PK\_PRIVATE\_OPTIMIZED}, {\bf PK\_PRIVATE} and {\bf PK\_PUBLIC}. The first |
|
|
2120 two are private keys where the ``optimized'' type uses the Chinese Remainder Theorem to speed up decryption/signatures. By |
|
|
2121 default all new keys are of the ``optimized'' type. The non-optimized private type is provided for backwards compatibility |
|
|
2122 as well as to save space since the optimized key requires about four times as much memory. |
|
|
2123 |
|
|
2124 \subsection{RSA Exponentiation} |
|
|
2125 |
|
|
2126 To do raw work with the RSA function call: |
|
|
2127 \index{rsa\_exptmod()} |
|
|
2128 \begin{verbatim} |
|
|
2129 int rsa_exptmod(const unsigned char *in, unsigned long inlen, |
|
|
2130 unsigned char *out, unsigned long *outlen, int which, |
|
|
2131 prng_state *prng, int prng_idx, |
|
|
2132 rsa_key *key); |
|
|
2133 \end{verbatim} |
|
|
2134 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 |
|
|
2135 in ``out'' and the size of the result in ``outlen''. ``which'' is set to {\bf PK\_PUBLIC} to use ``e'' |
|
|
2136 (i.e. for encryption/verifying) and set to {\bf PK\_PRIVATE} to use ``d'' as the exponent (i.e. for decrypting/signing). |
|
|
2137 |
|
|
2138 Note that the output of his function is zero-padded as per PKCS \#1 specifications. This allows this routine to |
|
|
2139 interoprate with PKCS \#1 padding functions properly. |
|
|
2140 |
|
|
2141 \subsection{RSA Key Encryption} |
|
|
2142 Normally RSA is used to encrypt short symmetric keys which are then used in block ciphers to encrypt a message. |
|
|
2143 To facilitate encrypting short keys the following functions have been provided. |
|
|
2144 |
|
|
2145 \index{rsa\_encrypt\_key()} |
|
|
2146 \begin{verbatim} |
|
|
2147 int rsa_encrypt_key(const unsigned char *inkey, unsigned long inlen, |
|
|
2148 unsigned char *outkey, unsigned long *outlen, |
|
|
2149 const unsigned char *lparam, unsigned long lparamlen, |
|
|
2150 prng_state *prng, int prng_idx, int hash_idx, rsa_key *key); |
|
|
2151 \end{verbatim} |
|
|
2152 This function will OAEP pad ``inkey'' of length inlen bytes then RSA encrypt it and store the ciphertext |
|
|
2153 in ``outkey'' of length ``outlen''. The ``lparam'' and ``lparamlen'' are the same parameters you would pass |
|
|
2154 to pkcs\_1\_oaep\_encode(). |
|
|
2155 |
|
|
2156 \index{rsa\_decrypt\_key()} |
|
|
2157 \begin{verbatim} |
|
|
2158 int rsa_decrypt_key(const unsigned char *in, unsigned long inlen, |
|
|
2159 unsigned char *outkey, unsigned long *keylen, |
|
|
2160 const unsigned char *lparam, unsigned long lparamlen, |
|
|
2161 prng_state *prng, int prng_idx, |
|
|
2162 int hash_idx, int *res, |
|
|
2163 rsa_key *key); |
|
|
2164 \end{verbatim} |
|
|
2165 This function will RSA decrypt ``in'' of length ``inlen'' then OAEP depad the resulting data and store it in |
|
|
2166 ``outkey'' of length ``outlen''. The ``lparam'' and ``lparamlen'' are the same parameters you would pass |
|
|
2167 to pkcs\_1\_oaep\_decode(). |
|
|
2168 |
|
|
2169 If the RSA decrypted data isn't a valid OAEP packet then ``res'' is set to $0$. Otherwise, it is set to $1$. |
|
|
2170 |
|
|
2171 \subsection{RSA Hash Signatures} |
|
|
2172 Similar to RSA key encryption RSA is also used to ``digitally sign'' message digests (hashes). To facilitate this |
|
|
2173 process the following functions have been provided. |
|
|
2174 |
|
|
2175 \index{rsa\_sign\_hash()} |
|
|
2176 \begin{verbatim} |
|
|
2177 int rsa_sign_hash(const unsigned char *msghash, unsigned long msghashlen, |
|
|
2178 unsigned char *sig, unsigned long *siglen, |
|
|
2179 prng_state *prng, int prng_idx, |
|
|
2180 int hash_idx, unsigned long saltlen, |
|
|
2181 rsa_key *key); |
|
|
2182 \end{verbatim} |
|
|
2183 |
|
|
2184 This will PSS encode the message hash ``msghash'' of length ``msghashlen''. Next the PSS encoded message is |
|
|
2185 RSA ``signed'' and the output is stored in ``sig'' of length ``siglen''. |
|
|
2186 |
|
|
2187 |
|
|
2188 \index{rsa\_verify\_hash()} |
|
|
2189 \begin{verbatim} |
|
|
2190 int rsa_verify_hash(const unsigned char *sig, unsigned long siglen, |
|
|
2191 const unsigned char *msghash, unsigned long msghashlen, |
|
|
2192 prng_state *prng, int prng_idx, |
|
|
2193 int hash_idx, unsigned long saltlen, |
|
|
2194 int *stat, rsa_key *key); |
|
|
2195 \end{verbatim} |
|
|
2196 |
|
|
2197 This will RSA ``verify'' the signature in ``sig'' of length ``siglen''. Next the RSA decoded data is PSS decoded |
|
|
2198 and the extracted hash is compared against the message hash ``msghash'' of length ``msghashlen''. |
|
|
2199 |
|
|
2200 If the RSA decoded data is not a valid PSS message or if the PSS decoded hash does not match the ``msghash'' |
|
|
2201 the value ``res'' is set to $0$. Otherwise, if the function succeeds and signature is valid ``res'' is set |
|
|
2202 to $1$. |
|
|
2203 |
|
|
2204 \begin{verbatim} |
|
|
2205 #include <mycrypt.h> |
|
|
2206 int main(void) |
|
|
2207 { |
|
|
2208 int err, hash_idx, prng_idx, res; |
|
|
2209 unsigned long l1, l2; |
|
|
2210 unsigned char pt[16], pt2[16], out[1024]; |
|
|
2211 rsa_key key; |
|
|
2212 |
|
|
2213 /* register prng/hash */ |
|
|
2214 if (register_prng(&sprng_desc) == -1) { |
|
|
2215 printf("Error registering sprng"); |
|
|
2216 return EXIT_FAILURE; |
|
|
2217 } |
|
|
2218 |
|
|
2219 if (register_hash(&sha1_desc) == -1) { |
|
|
2220 printf("Error registering sha1"); |
|
|
2221 return EXIT_FAILURE; |
|
|
2222 } |
|
|
2223 hash_idx = find_hash("sha1"); |
|
|
2224 prng_idx = find_prng("sprng"); |
|
|
2225 |
|
|
2226 /* make an RSA-1024 key */ |
|
|
2227 if ((err = rsa_make_key(NULL, /* PRNG state */ |
|
|
2228 prng_idx, /* PRNG idx */ |
|
|
2229 1024/8, /* 1024-bit key */ |
|
|
2230 65537, /* we like e=65537 */ |
|
|
2231 &key) /* where to store the key */ |
|
|
2232 ) != CRYPT_OK) { |
|
|
2233 printf("rsa_make_key %s", error_to_string(err)); |
|
|
2234 return EXIT_FAILURE; |
|
|
2235 } |
|
|
2236 |
|
|
2237 /* fill in pt[] with a key we want to send ... */ |
|
|
2238 l1 = sizeof(out); |
|
|
2239 if ((err = rsa_encrypt_key(pt, /* data we wish to encrypt */ |
|
|
2240 16, /* data is 16 bytes long */ |
|
|
2241 out, /* where to store ciphertext */ |
|
|
2242 &l1, /* length of ciphertext */ |
|
|
2243 "TestApp", /* our lparam for this program */ |
|
|
2244 7, /* lparam is 7 bytes long */ |
|
|
2245 NULL, /* PRNG state */ |
|
|
2246 prng_idx, /* prng idx */ |
|
|
2247 hash_idx, /* hash idx */ |
|
|
2248 &key) /* our RSA key */ |
|
|
2249 ) != CRYPT_OK) { |
|
|
2250 printf("rsa_encrypt_key %s", error_to_string(err)); |
|
|
2251 return EXIT_FAILURE; |
|
|
2252 } |
|
|
2253 |
|
|
2254 /* now let's decrypt the encrypted key */ |
|
|
2255 l2 = sizeof(pt2); |
|
|
2256 if ((err = rsa_decrypt_key(out, /* encrypted data */ |
|
|
2257 l1, /* length of ciphertext */ |
|
|
2258 pt2, /* where to put plaintext */ |
|
|
2259 &l2, /* plaintext length */ |
|
|
2260 "TestApp", /* lparam for this program */ |
|
|
2261 7, /* lparam is 7 bytes long */ |
|
|
2262 NULL, /* PRNG state */ |
|
|
2263 prng_idx, /* prng idx */ |
|
|
2264 hash_idx, /* hash idx */ |
|
|
2265 &res, /* validity of data */ |
|
|
2266 &key) /* our RSA key */ |
|
|
2267 ) != CRYPT_OK) { |
|
|
2268 printf("rsa_decrypt_key %s", error_to_string(err)); |
|
|
2269 return EXIT_FAILURE; |
|
|
2270 } |
|
|
2271 /* if all went well pt == pt2, l2 == 16, res == 1 */ |
|
|
2272 } |
|
|
2273 \end{verbatim} |
|
|
2274 |
|
3
|
2275 \chapter{Password Based Cryptography} |
|
|
2276 \section{PKCS \#5} |
|
|
2277 In order to securely handle user passwords for the purposes of creating session keys and chaining IVs the PKCS \#5 was drafted. PKCS \#5 |
|
|
2278 is made up of two algorithms, Algorithm One and Algorithm Two. Algorithm One is the older fairly limited algorithm which has been implemented |
|
|
2279 for completeness. Algorithm Two is a bit more modern and more flexible to work with. |
|
|
2280 |
|
|
2281 \section{Algorithm One} |
|
|
2282 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 |
|
|
2283 people trying to brute force guess the password. The higher the iteration counter the longer the delay. This algorithm also requires a hash |
|
|
2284 algorithm and produces an output no longer than the output of the hash. |
|
|
2285 |
|
15
|
2286 \index{pkcs\_5\_alg1()} |
|
3
|
2287 \begin{alltt} |
|
|
2288 int pkcs_5_alg1(const unsigned char *password, unsigned long password_len, |
|
|
2289 const unsigned char *salt, |
|
|
2290 int iteration_count, int hash_idx, |
|
|
2291 unsigned char *out, unsigned long *outlen) |
|
|
2292 \end{alltt} |
|
|
2293 Where ``password'' is the users password. Since the algorithm allows binary passwords you must also specify the length in ``password\_len''. |
|
|
2294 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 |
|
|
2295 on the password. The ``hash\_idx'' is the index of the hash you wish to use in the descriptor table. |
|
|
2296 |
|
|
2297 The output of length upto ``outlen'' is stored in ``out''. If ``outlen'' is initially larger than the size of the hash functions output |
|
|
2298 it is set to the number of bytes stored. If it is smaller than not all of the hash output is stored in ``out''. |
|
|
2299 |
|
|
2300 \section{Algorithm Two} |
|
|
2301 |
|
|
2302 Algorithm Two is the recommended algorithm for this task. It allows variable length salts and can produce outputs larger than the |
|
|
2303 hash functions output. As such it can easily be used to derive session keys for ciphers and MACs as well initial vectors as required |
|
|
2304 from a single password and invokation of this algorithm. |
|
|
2305 |
|
15
|
2306 \index{pkcs\_5\_alg2()} |
|
3
|
2307 \begin{alltt} |
|
|
2308 int pkcs_5_alg2(const unsigned char *password, unsigned long password_len, |
|
|
2309 const unsigned char *salt, unsigned long salt_len, |
|
|
2310 int iteration_count, int hash_idx, |
|
|
2311 unsigned char *out, unsigned long *outlen) |
|
|
2312 \end{alltt} |
|
|
2313 Where ``password'' is the users password. Since the algorithm allows binary passwords you must also specify the length in ``password\_len''. |
|
|
2314 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 |
|
|
2315 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 |
|
|
2316 ``outlen'' is stored in ``out''. |
|
|
2317 |
|
|
2318 \begin{alltt} |
|
|
2319 /* demo to show how to make session state material from a password */ |
|
|
2320 #include <mycrypt.h> |
|
|
2321 int main(void) |
|
|
2322 \{ |
|
|
2323 unsigned char password[100], salt[100], |
|
|
2324 cipher_key[16], cipher_iv[16], |
|
|
2325 mac_key[16], outbuf[48]; |
|
|
2326 int err, hash_idx; |
|
|
2327 unsigned long outlen, password_len, salt_len; |
|
|
2328 |
|
|
2329 /* register hash and get it's idx .... */ |
|
|
2330 |
|
|
2331 /* get users password and make up a salt ... */ |
|
|
2332 |
|
|
2333 /* create the material (100 iterations in algorithm) */ |
|
|
2334 outlen = sizeof(outbuf); |
|
|
2335 if ((err = pkcs_5_alg2(password, password_len, salt, salt_len, |
|
|
2336 100, hash_idx, outbuf, &outlen)) != CRYPT_OK) \{ |
|
|
2337 /* error handle */ |
|
|
2338 \} |
|
|
2339 |
|
|
2340 /* now extract it */ |
|
|
2341 memcpy(cipher_key, outbuf, 16); |
|
|
2342 memcpy(cipher_iv, outbuf+16, 16); |
|
|
2343 memcpy(mac_key, outbuf+32, 16); |
|
|
2344 |
|
|
2345 /* use material (recall to store the salt in the output) */ |
|
|
2346 \} |
|
|
2347 \end{alltt} |
|
|
2348 |
|
|
2349 \chapter{Diffie-Hellman Key Exchange} |
|
|
2350 |
|
|
2351 \section{Background} |
|
|
2352 |
|
|
2353 Diffie-Hellman was the original public key system proposed. The system is based upon the group structure |
|
|
2354 of finite fields. For Diffie-Hellman a prime $p$ is chosen and a ``base'' $b$ such that $b^x\mbox{ }(\mbox{mod }p)$ |
|
|
2355 generates a large sub-group of prime order (for unique values of $x$). |
|
|
2356 |
|
|
2357 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 |
|
|
2358 ``discrete logarithm'' denotes the action of finding $x$ given only $y$, $g$ and $p$. The key exchange part of |
|
|
2359 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 |
|
|
2360 a shared key $K \equiv B_y^{A_x} \equiv A_y^{B_x} \equiv g^{A_xB_x}\mbox{ }(\mbox{mod }p)$. |
|
|
2361 |
|
|
2362 From this public encryption and signatures can be developed. The trivial way to encrypt (for example) using a public key |
|
|
2363 $y$ is to perform the key exchange offline. The sender invents a key $k$ and its public copy |
|
|
2364 $k' \equiv g^k\mbox{ }(\mbox{mod }p)$ and uses $K \equiv k'^{A_x}\mbox{ }(\mbox{mod }p)$ as a key to encrypt |
|
|
2365 the message with. Typically $K$ would be sent to a one-way hash and the message digested used as a key in a |
|
|
2366 symmetric cipher. |
|
|
2367 |
|
|
2368 It is important that the order of the sub-group that $g$ generates not only be large but also prime. There are |
|
|
2369 discrete logarithm algorithms that take $\sqrt r$ time given the order $r$. The discrete logarithm can be computed |
|
|
2370 modulo each prime factor of $r$ and the results combined using the Chinese Remainder Theorem. In the cases where |
|
|
2371 $r$ is ``B-Smooth'' (e.g. all small factors or powers of small prime factors) the solution is trivial to find. |
|
|
2372 |
|
|
2373 To thwart such attacks the primes and bases in the library have been designed and fixed. Given a prime $p$ the order of |
|
|
2374 the sub-group generated is a large prime namely ${p - 1} \over 2$. Such primes are known as ``strong primes'' and the |
|
|
2375 smaller prime (e.g. the order of the base) are known as Sophie-Germaine primes. |
|
|
2376 |
|
|
2377 \section{Core Functions} |
|
|
2378 |
|
|
2379 This library also provides core Diffie-Hellman functions so you can negotiate keys over insecure mediums. The routines |
|
|
2380 provided are relatively easy to use and only take two function calls to negotiate a shared key. There is a structure |
|
|
2381 called ``dh\_key'' which stores the Diffie-Hellman key in a format these routines can use. The first routine is to |
|
|
2382 make a Diffie-Hellman private key pair: |
|
|
2383 \index{dh\_make\_key()} |
|
|
2384 \begin{verbatim} |
|
|
2385 int dh_make_key(prng_state *prng, int wprng, |
|
|
2386 int keysize, dh_key *key); |
|
|
2387 \end{verbatim} |
|
|
2388 The ``keysize'' is the size of the modulus you want in bytes. Currently support sizes are 96 to 512 bytes which correspond |
|
|
2389 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 |
|
|
2390 specifying a size not explicitly supported by the library it will round {\em up} to the next key size. If the size is |
|
|
2391 above 512 it will return an error. So if you pass ``keysize == 32'' it will use a 768 bit key but if you pass |
|
|
2392 ``keysize == 20000'' it will return an error. The primes and generators used are built-into the library and were designed |
|
|
2393 to meet very specific goals. The primes are strong primes which means that if $p$ is the prime then |
|
|
2394 $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 |
|
|
2395 leaking a bit of the key. This means the bases generate a very large prime order group which is good to make cryptanalysis |
|
|
2396 hard. |
|
|
2397 |
|
|
2398 The next two routines are for exporting/importing Diffie-Hellman keys in a binary format. This is useful for transport |
|
|
2399 over communication mediums. |
|
|
2400 |
|
|
2401 \index{dh\_export()} \index{dh\_import()} |
|
|
2402 \begin{verbatim} |
|
|
2403 int dh_export(unsigned char *out, unsigned long *outlen, |
|
|
2404 int type, dh_key *key); |
|
|
2405 |
|
|
2406 int dh_import(const unsigned char *in, unsigned long inlen, dh_key *key); |
|
|
2407 \end{verbatim} |
|
|
2408 |
|
|
2409 These two functions work just like the ``rsa\_export()'' and ``rsa\_import()'' functions except these work with |
|
|
2410 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 |
|
|
2411 ``dh\_key'' using: |
|
|
2412 \begin{verbatim} |
|
|
2413 void dh_free(dh_key *key); |
|
|
2414 \end{verbatim} |
|
|
2415 After you have exported a copy of your public key (using {\bf PK\_PUBLIC} as ``type'') you can now create a shared secret |
|
|
2416 with the other user using: |
|
|
2417 \index{dh\_shared\_secret()} |
|
|
2418 \begin{verbatim} |
|
|
2419 int dh_shared_secret(dh_key *private_key, |
|
|
2420 dh_key *public_key, |
|
|
2421 unsigned char *out, unsigned long *outlen); |
|
|
2422 \end{verbatim} |
|
|
2423 |
|
|
2424 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 |
|
|
2425 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 |
|
|
2426 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 |
|
|
2427 key: |
|
|
2428 \index{dh\_get\_size()} |
|
|
2429 \begin{verbatim} |
|
|
2430 int dh_get_size(dh_key *key); |
|
|
2431 \end{verbatim} |
|
|
2432 This returns the size in bytes of the modulus chosen for that key. |
|
|
2433 |
|
|
2434 \subsection{Remarks on Usage} |
|
|
2435 Its important that you hash the shared key before trying to use it as a key for a symmetric cipher or something. An |
|
|
2436 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.}: |
|
|
2437 \newpage |
|
|
2438 \begin{small} |
|
|
2439 \begin{verbatim} |
|
|
2440 int establish_secure_socket(int sock, int mode, unsigned char *key, |
|
|
2441 prng_state *prng, int wprng) |
|
|
2442 { |
|
|
2443 unsigned char buf[4096], buf2[4096]; |
|
|
2444 unsigned long x, len; |
|
|
2445 int res, err, inlen; |
|
|
2446 dh_key mykey, theirkey; |
|
|
2447 |
|
|
2448 /* make up our private key */ |
|
|
2449 if ((err = dh_make_key(prng, wprng, 128, &mykey)) != CRYPT_OK) { |
|
|
2450 return err; |
|
|
2451 } |
|
|
2452 |
|
|
2453 /* export our key as public */ |
|
|
2454 x = sizeof(buf); |
|
|
2455 if ((err = dh_export(buf, &x, PK_PUBLIC, &mykey)) != CRYPT_OK) { |
|
|
2456 res = err; |
|
|
2457 goto done2; |
|
|
2458 } |
|
|
2459 |
|
|
2460 if (mode == 0) { |
|
|
2461 /* mode 0 so we send first */ |
|
|
2462 if (send(sock, buf, x, 0) != x) { |
|
|
2463 res = CRYPT_ERROR; |
|
|
2464 goto done2; |
|
|
2465 } |
|
|
2466 |
|
|
2467 /* get their key */ |
|
|
2468 if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) { |
|
|
2469 res = CRYPT_ERROR; |
|
|
2470 goto done2; |
|
|
2471 } |
|
|
2472 } else { |
|
|
2473 /* mode >0 so we send second */ |
|
|
2474 if ((inlen = recv(sock, buf2, sizeof(buf2), 0)) <= 0) { |
|
|
2475 res = CRYPT_ERROR; |
|
|
2476 goto done2; |
|
|
2477 } |
|
|
2478 |
|
|
2479 if (send(sock, buf, x, 0) != x) { |
|
|
2480 res = CRYPT_ERROR; |
|
|
2481 goto done2; |
|
|
2482 } |
|
|
2483 } |
|
|
2484 |
|
|
2485 if ((err = dh_import(buf2, inlen, &theirkey)) != CRYPT_OK) { |
|
|
2486 res = err; |
|
|
2487 goto done2; |
|
|
2488 } |
|
|
2489 |
|
|
2490 /* make shared secret */ |
|
|
2491 x = sizeof(buf); |
|
|
2492 if ((err = dh_shared_secret(&mykey, &theirkey, buf, &x)) != CRYPT_OK) { |
|
|
2493 res = err; |
|
|
2494 goto done; |
|
|
2495 } |
|
|
2496 |
|
|
2497 /* hash it */ |
|
|
2498 len = 16; /* default is MD5 so "key" must be at least 16 bytes long */ |
|
|
2499 if ((err = hash_memory(find_hash("md5"), buf, x, key, &len)) != CRYPT_OK) { |
|
|
2500 res = err; |
|
|
2501 goto done; |
|
|
2502 } |
|
|
2503 |
|
|
2504 /* clean up and return */ |
|
|
2505 res = CRYPT_OK; |
|
|
2506 done: |
|
|
2507 dh_free(&theirkey); |
|
|
2508 done2: |
|
|
2509 dh_free(&mykey); |
|
|
2510 zeromem(buf, sizeof(buf)); |
|
|
2511 zeromem(buf2, sizeof(buf2)); |
|
|
2512 return res; |
|
|
2513 } |
|
|
2514 \end{verbatim} |
|
|
2515 \end{small} |
|
|
2516 \newpage |
|
|
2517 \subsection{Remarks on The Snippet} |
|
|
2518 When the above code snippet is done (assuming all went well) their will be a shared 128-bit key in the ``key'' array |
|
|
2519 passed to ``establish\_secure\_socket()''. |
|
|
2520 |
|
|
2521 \section{Other Diffie-Hellman Functions} |
|
|
2522 In order to test the Diffie-Hellman function internal workings (e.g. the primes and bases) their is a test function made |
|
|
2523 available: |
|
|
2524 \index{dh\_test()} |
|
|
2525 \begin{verbatim} |
|
|
2526 int dh_test(void); |
|
|
2527 \end{verbatim} |
|
|
2528 |
|
|
2529 This function returns {\bf CRYPT\_OK} if the bases and primes in the library are correct. There is one last helper |
|
|
2530 function: |
|
|
2531 \index{dh\_sizes()} |
|
|
2532 \begin{verbatim} |
|
|
2533 void dh_sizes(int *low, int *high); |
|
|
2534 \end{verbatim} |
|
|
2535 Which stores the smallest and largest key sizes support into the two variables. |
|
|
2536 |
|
|
2537 \section{DH Packet} |
|
|
2538 Similar to the RSA related functions there are functions to encrypt or decrypt symmetric keys using the DH public key |
|
|
2539 algorithms. |
|
15
|
2540 \index{dh\_encrypt\_key()} \index{dh\_decrypt\_key()} |
|
3
|
2541 \begin{verbatim} |
|
|
2542 int dh_encrypt_key(const unsigned char *inkey, unsigned long keylen, |
|
|
2543 unsigned char *out, unsigned long *len, |
|
|
2544 prng_state *prng, int wprng, int hash, |
|
|
2545 dh_key *key); |
|
|
2546 |
|
|
2547 int dh_decrypt_key(const unsigned char *in, unsigned long inlen, |
|
|
2548 unsigned char *outkey, unsigned long *keylen, |
|
|
2549 dh_key *key); |
|
|
2550 \end{verbatim} |
|
|
2551 Where ``inkey'' is an input symmetric key of no more than 32 bytes. Essentially these routines created a random public key |
|
|
2552 and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the |
|
|
2553 required data is placed in ``out'' by ``dh\_encrypt\_key()''. The hash must produce a message digest at least as large |
|
|
2554 as the symmetric key you are trying to share. |
|
|
2555 |
|
|
2556 Similar to the RSA system you can sign and verify a hash of a message. |
|
15
|
2557 \index{dh\_sign\_hash()} \index{dh\_verify\_hash()} |
|
3
|
2558 \begin{verbatim} |
|
|
2559 int dh_sign_hash(const unsigned char *in, unsigned long inlen, |
|
|
2560 unsigned char *out, unsigned long *outlen, |
|
|
2561 prng_state *prng, int wprng, dh_key *key); |
|
|
2562 |
|
|
2563 int dh_verify_hash(const unsigned char *sig, unsigned long siglen, |
|
|
2564 const unsigned char *hash, unsigned long hashlen, |
|
|
2565 int *stat, dh_key *key); |
|
|
2566 \end{verbatim} |
|
|
2567 |
|
|
2568 The ``dh\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a DH packet in ``out''. |
|
|
2569 The ``dh\_verify\_hash'' function verifies the DH signature in ``sig'' against the hash in ``hash''. It sets ``stat'' |
|
|
2570 to non-zero if the signature passes or zero if it fails. |
|
|
2571 |
|
|
2572 \chapter{Elliptic Curve Cryptography} |
|
|
2573 |
|
|
2574 \section{Background} |
|
|
2575 The library provides a set of core ECC functions as well that are designed to be the Elliptic Curve analogy of all of the |
|
|
2576 Diffie-Hellman routines in the previous chapter. Elliptic curves (of certain forms) have the benefit that they are harder |
|
|
2577 to attack (no sub-exponential attacks exist unlike normal DH crypto) in fact the fastest attack requires the square root |
|
|
2578 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 |
|
|
2579 192-bit key) then the work factor is $2^{96}$ in order to find the secret key. |
|
|
2580 |
|
|
2581 The curves in this library are taken from the following website: |
|
|
2582 \begin{verbatim} |
|
|
2583 http://csrc.nist.gov/cryptval/dss.htm |
|
|
2584 \end{verbatim} |
|
|
2585 |
|
|
2586 They are all curves over the integers modulo a prime. The curves have the basic equation that is: |
|
|
2587 \begin{equation} |
|
|
2588 y^2 = x^3 - 3x + b\mbox{ }(\mbox{mod }p) |
|
|
2589 \end{equation} |
|
|
2590 |
|
|
2591 The variable $b$ is chosen such that the number of points is nearly maximal. In fact the order of the base points $\beta$ |
|
|
2592 provided are very close to $p$ that is $\vert \vert \phi(\beta) \vert \vert \approx \vert \vert p \vert \vert$. The curves |
|
|
2593 range in order from $\approx 2^{192}$ points to $\approx 2^{521}$. According to the source document any key size greater |
|
|
2594 than or equal to 256-bits is sufficient for long term security. |
|
|
2595 |
|
|
2596 \section{Core Functions} |
|
|
2597 |
|
|
2598 Like the DH routines there is a key structure ``ecc\_key'' used by the functions. There is a function to make a key: |
|
|
2599 \index{ecc\_make\_key()} |
|
|
2600 \begin{verbatim} |
|
|
2601 int ecc_make_key(prng_state *prng, int wprng, |
|
|
2602 int keysize, ecc_key *key); |
|
|
2603 \end{verbatim} |
|
|
2604 |
|
|
2605 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 |
|
|
2606 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 |
|
|
2607 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. |
|
|
2608 To free the ram allocated by a key call: |
|
|
2609 \index{ecc\_free()} |
|
|
2610 \begin{verbatim} |
|
|
2611 void ecc_free(ecc_key *key); |
|
|
2612 \end{verbatim} |
|
|
2613 |
|
|
2614 To import and export a key there are: |
|
|
2615 \index{ecc\_export()} |
|
|
2616 \index{ecc\_import()} |
|
|
2617 \begin{verbatim} |
|
|
2618 int ecc_export(unsigned char *out, unsigned long *outlen, |
|
|
2619 int type, ecc_key *key); |
|
|
2620 |
|
|
2621 int ecc_import(const unsigned char *in, unsigned long inlen, ecc_key *key); |
|
|
2622 \end{verbatim} |
|
|
2623 These two work exactly like there DH counterparts. Finally when you share your public key you can make a shared secret |
|
|
2624 with: |
|
|
2625 \index{ecc\_shared\_secret()} |
|
|
2626 \begin{verbatim} |
|
|
2627 int ecc_shared_secret(ecc_key *private_key, |
|
|
2628 ecc_key *public_key, |
|
|
2629 unsigned char *out, unsigned long *outlen); |
|
|
2630 \end{verbatim} |
|
|
2631 Which works exactly like the DH counterpart, the ``private\_key'' is your own key and ``public\_key'' is the key the other |
|
|
2632 user sent you. Note that this function stores both $x$ and $y$ co-ordinates of the shared |
|
|
2633 elliptic point. You should hash the output to get a shared key in a more compact and useful form (most of the entropy is |
|
|
2634 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 |
|
|
2635 of a key. |
|
|
2636 \index{ecc\_get\_size()} |
|
|
2637 \begin{verbatim} |
|
|
2638 int ecc_get_size(ecc_key *key); |
|
|
2639 \end{verbatim} |
|
|
2640 |
|
|
2641 To test the ECC routines and to get the minimum and maximum key sizes there are these two functions: |
|
|
2642 \index{ecc\_test()} |
|
|
2643 \begin{verbatim} |
|
|
2644 int ecc_test(void); |
|
|
2645 void ecc_sizes(int *low, int *high); |
|
|
2646 \end{verbatim} |
|
|
2647 Which both work like their DH counterparts. |
|
|
2648 |
|
|
2649 \section{ECC Packet} |
|
|
2650 Similar to the RSA API there are two functions which encrypt and decrypt symmetric keys using the ECC public key |
|
|
2651 algorithms. |
|
15
|
2652 |
|
|
2653 \index{ecc\_encrypt\_key()} \index{ecc\_decrypt\_key()} |
|
3
|
2654 \begin{verbatim} |
|
|
2655 int ecc_encrypt_key(const unsigned char *inkey, unsigned long keylen, |
|
|
2656 unsigned char *out, unsigned long *len, |
|
|
2657 prng_state *prng, int wprng, int hash, |
|
|
2658 ecc_key *key); |
|
|
2659 |
|
|
2660 int ecc_decrypt_key(const unsigned char *in, unsigned long inlen, |
|
|
2661 unsigned char *outkey, unsigned long *keylen, |
|
|
2662 ecc_key *key); |
|
|
2663 \end{verbatim} |
|
|
2664 |
|
|
2665 Where ``inkey'' is an input symmetric key of no more than 32 bytes. Essentially these routines created a random public key |
|
|
2666 and find the hash of the shared secret. The message digest is than XOR'ed against the symmetric key. All of the required |
|
|
2667 data is placed in ``out'' by ``ecc\_encrypt\_key()''. The hash chosen must produce a message digest at least as large |
|
|
2668 as the symmetric key you are trying to share. |
|
|
2669 |
|
|
2670 There are also functions to sign and verify the hash of a message. |
|
15
|
2671 \index{ecc\_sign\_hash()} \index{ecc\_verify\_hash()} |
|
3
|
2672 \begin{verbatim} |
|
|
2673 int ecc_sign_hash(const unsigned char *in, unsigned long inlen, |
|
|
2674 unsigned char *out, unsigned long *outlen, |
|
|
2675 prng_state *prng, int wprng, ecc_key *key); |
|
|
2676 |
|
|
2677 int ecc_verify_hash(const unsigned char *sig, unsigned long siglen, |
|
|
2678 const unsigned char *hash, unsigned long hashlen, |
|
|
2679 int *stat, ecc_key *key); |
|
|
2680 \end{verbatim} |
|
|
2681 |
|
|
2682 The ``ecc\_sign\_hash'' function signs the message hash in ``in'' of length ``inlen'' and forms a ECC packet in ``out''. |
|
|
2683 The ``ecc\_verify\_hash'' function verifies the ECC signature in ``sig'' against the hash in ``hash''. It sets ``stat'' |
|
|
2684 to non-zero if the signature passes or zero if it fails. |
|
|
2685 |
|
|
2686 |
|
|
2687 \section{ECC Keysizes} |
|
|
2688 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 |
|
|
2689 and in effect the signature will still work. With ECC keys the strength of the signature is limited by the size of |
|
|
2690 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 |
|
|
2691 you have 160-bits of security (e.g. as if you signed with SHA-1). |
|
|
2692 |
|
|
2693 The library will not warn you if you make this mistake so it is important to check yourself before using the |
|
|
2694 signatures. |
|
|
2695 |
|
|
2696 \chapter{Digital Signature Algorithm} |
|
|
2697 \section{Introduction} |
|
|
2698 The Digital Signature Algorithm (or DSA) is a variant of the ElGamal Signature scheme which has been modified to |
|
|
2699 reduce the bandwidth of a signature. For example, to have ``80-bits of security'' with ElGamal you need a group of |
|
|
2700 order at least 1024-bits. With DSA you need a group of order at least 160-bits. By comparison the ElGamal signature |
|
|
2701 would require at least 256 bytes where as the DSA signature would require only at least 40 bytes. |
|
|
2702 |
|
|
2703 The API for the DSA is essentially the same as the other PK algorithms. Except in the case of DSA no encryption or |
|
|
2704 decryption routines are provided. |
|
|
2705 |
|
|
2706 \section{Key Generation} |
|
|
2707 To make a DSA key you must call the following function |
|
|
2708 \begin{verbatim} |
|
|
2709 int dsa_make_key(prng_state *prng, int wprng, |
|
|
2710 int group_size, int modulus_size, |
|
|
2711 dsa_key *key); |
|
|
2712 \end{verbatim} |
|
|
2713 The variable ``prng'' is an active PRNG state and ``wprng'' the index to the descriptor. ``group\_size'' and |
|
|
2714 ``modulus\_size'' control the difficulty of forging a signature. Both parameters are in bytes. The larger the |
|
|
2715 ``group\_size'' the more difficult a forgery becomes upto a limit. The value of $group\_size$ is limited by |
|
|
2716 $15 < group\_size < 1024$ and $modulus\_size - group\_size < 512$. Suggested values for the pairs are as follows. |
|
|
2717 |
|
|
2718 \begin{center} |
|
|
2719 \begin{tabular}{|c|c|c|} |
|
|
2720 \hline \textbf{Bits of Security} & \textbf{group\_size} & \textbf{modulus\_size} \\ |
|
|
2721 \hline 80 & 20 & 128 \\ |
|
|
2722 \hline 120 & 30 & 256 \\ |
|
|
2723 \hline 140 & 35 & 384 \\ |
|
|
2724 \hline 160 & 40 & 512 \\ |
|
|
2725 \hline |
|
|
2726 \end{tabular} |
|
|
2727 \end{center} |
|
|
2728 |
|
|
2729 When you are finished with a DSA key you can call the following function to free the memory used. |
|
15
|
2730 \index{dsa\_free()} |
|
3
|
2731 \begin{verbatim} |
|
|
2732 void dsa_free(dsa_key *key); |
|
|
2733 \end{verbatim} |
|
|
2734 |
|
|
2735 \section{Key Verification} |
|
|
2736 Each DSA key is composed of the following variables. |
|
|
2737 |
|
|
2738 \begin{enumerate} |
|
|
2739 \item $q$ a small prime of magnitude $256^{group\_size}$. |
|
|
2740 \item $p = qr + 1$ a large prime of magnitude $256^{modulus\_size}$ where $r$ is a random even integer. |
|
|
2741 \item $g = h^r \mbox{ (mod }p\mbox{)}$ a generator of order $q$ modulo $p$. $h$ can be any non-trivial random |
|
|
2742 value. For this library they start at $h = 2$ and step until $g$ is not $1$. |
|
|
2743 \item $x$ a random secret (the secret key) in the range $1 < x < q$ |
|
|
2744 \item $y = g^x \mbox{ (mod }p\mbox{)}$ the public key. |
|
|
2745 \end{enumerate} |
|
|
2746 |
|
|
2747 A DSA key is considered valid if it passes all of the following tests. |
|
|
2748 |
|
|
2749 \begin{enumerate} |
|
|
2750 \item $q$ must be prime. |
|
|
2751 \item $p$ must be prime. |
|
|
2752 \item $g$ cannot be one of $\lbrace -1, 0, 1 \rbrace$ (modulo $p$). |
|
|
2753 \item $g$ must be less than $p$. |
|
|
2754 \item $(p-1) \equiv 0 \mbox{ (mod }q\mbox{)}$. |
|
|
2755 \item $g^q \equiv 1 \mbox{ (mod }p\mbox{)}$. |
|
|
2756 \item $1 < y < p - 1$ |
|
|
2757 \item $y^q \equiv 1 \mbox{ (mod }p\mbox{)}$. |
|
|
2758 \end{enumerate} |
|
|
2759 |
|
|
2760 Tests one and two ensure that the values will at least form a field which is required for the signatures to |
|
|
2761 function. Tests three and four ensure that the generator $g$ is not set to a trivial value which would make signature |
|
|
2762 forgery easier. Test five ensures that $q$ divides the order of multiplicative sub-group of $\Z/p\Z$. Test six |
|
|
2763 ensures that the generator actually generates a prime order group. Tests seven and eight ensure that the public key |
|
|
2764 is within range and belongs to a group of prime order. Note that test eight does not prove that $g$ generated $y$ only |
|
|
2765 that $y$ belongs to a multiplicative sub-group of order $q$. |
|
|
2766 |
|
|
2767 The following function will perform these tests. |
|
|
2768 |
|
15
|
2769 \index{dsa\_verify\_key()} |
|
3
|
2770 \begin{verbatim} |
|
|
2771 int dsa_verify_key(dsa_key *key, int *stat); |
|
|
2772 \end{verbatim} |
|
|
2773 |
|
|
2774 This will test ``key'' and store the result in ``stat''. If the result is $stat = 0$ the DSA key failed one of the tests |
|
|
2775 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). |
|
|
2776 |
|
|
2777 |
|
|
2778 |
|
|
2779 \section{Signatures} |
|
|
2780 To generate a DSA signature call the following function |
|
|
2781 |
|
15
|
2782 \index{dsa\_sign\_hash()} |
|
3
|
2783 \begin{verbatim} |
|
|
2784 int dsa_sign_hash(const unsigned char *in, unsigned long inlen, |
|
|
2785 unsigned char *out, unsigned long *outlen, |
|
|
2786 prng_state *prng, int wprng, dsa_key *key); |
|
|
2787 \end{verbatim} |
|
|
2788 |
|
|
2789 Which will sign the data in ``in'' of length ``inlen'' bytes. The signature is stored in ``out'' and the size |
|
|
2790 of the signature in ``outlen''. If the signature is longer than the size you initially specify in ``outlen'' nothing |
|
|
2791 is stored and the function returns an error code. The DSA ``key'' must be of the \textbf{PK\_PRIVATE} persuasion. |
|
|
2792 |
|
|
2793 To verify a hash created with that function use the following function |
|
|
2794 |
|
15
|
2795 \index{dsa\_verify\_hash()} |
|
3
|
2796 \begin{verbatim} |
|
|
2797 int dsa_verify_hash(const unsigned char *sig, unsigned long siglen, |
|
|
2798 const unsigned char *hash, unsigned long inlen, |
|
|
2799 int *stat, dsa_key *key); |
|
|
2800 \end{verbatim} |
|
|
2801 Which will verify the data in ``hash'' of length ``inlen'' against the signature stored in ``sig'' of length ``siglen''. |
|
|
2802 It will set ``stat'' to $1$ if the signature is valid, otherwise it sets ``stat'' to $0$. |
|
|
2803 |
|
|
2804 \section{Import and Export} |
|
|
2805 |
|
|
2806 To export a DSA key so that it can be transported use the following function |
|
15
|
2807 \index{dsa\_export()} |
|
3
|
2808 \begin{verbatim} |
|
|
2809 int dsa_export(unsigned char *out, unsigned long *outlen, |
|
|
2810 int type, |
|
|
2811 dsa_key *key); |
|
|
2812 \end{verbatim} |
|
|
2813 This will export the DSA ``key'' to the buffer ``out'' and set the length in ``outlen'' (which must have been previously |
|
|
2814 initialized to the maximum buffer size). The ``type`` variable may be either \textbf{PK\_PRIVATE} or \textbf{PK\_PUBLIC} |
|
|
2815 depending on whether you want to export a private or public copy of the DSA key. |
|
|
2816 |
|
|
2817 To import an exported DSA key use the following function |
|
|
2818 |
|
15
|
2819 \index{dsa\_import()} |
|
3
|
2820 \begin{verbatim} |
|
|
2821 int dsa_import(const unsigned char *in, unsigned long inlen, |
|
|
2822 dsa_key *key); |
|
|
2823 \end{verbatim} |
|
|
2824 |
|
|
2825 This will import the DSA key from the buffer ``in'' of length ``inlen'' to the ``key''. If the process fails the function |
|
|
2826 will automatically free all of the heap allocated in the process (you don't have to call dsa\_free()). |
|
|
2827 |
|
|
2828 \chapter{Miscellaneous} |
|
|
2829 \section{Base64 Encoding and Decoding} |
|
|
2830 The library provides functions to encode and decode a RFC1521 base64 coding scheme. This means that it can decode what it |
|
|
2831 encodes but the format used does not comply to any known standard. The characters used in the mappings are: |
|
|
2832 \begin{verbatim} |
|
|
2833 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ |
|
|
2834 \end{verbatim} |
|
|
2835 Those characters should are supported in virtually any 7-bit ASCII system which means they can be used for transport over |
|
|
2836 common e-mail, usenet and HTTP mediums. The format of an encoded stream is just a literal sequence of ASCII characters |
|
|
2837 where a group of four represent 24-bits of input. The first four chars of the encoders output is the length of the |
|
|
2838 original input. After the first four characters is the rest of the message. |
|
|
2839 |
|
|
2840 Often it is desirable to line wrap the output to fit nicely in an e-mail or usenet posting. The decoder allows you to |
|
|
2841 put any character (that is not in the above sequence) in between any character of the encoders output. You may not however, |
|
|
2842 break up the first four characters. |
|
|
2843 |
|
|
2844 To encode a binary string in base64 call: |
|
|
2845 \index{base64\_encode()} \index{base64\_decode()} |
|
|
2846 \begin{verbatim} |
|
|
2847 int base64_encode(const unsigned char *in, unsigned long len, |
|
|
2848 unsigned char *out, unsigned long *outlen); |
|
|
2849 \end{verbatim} |
|
|
2850 Where ``in'' is the binary string and ``out'' is where the ASCII output is placed. You must set the value of ``outlen'' prior |
|
|
2851 to calling this function and it sets the length of the base64 output in ``outlen'' when it is done. To decode a base64 |
|
|
2852 string call: |
|
|
2853 \begin{verbatim} |
|
|
2854 int base64_decode(const unsigned char *in, unsigned long len, |
|
|
2855 unsigned char *out, unsigned long *outlen); |
|
|
2856 \end{verbatim} |
|
|
2857 |
|
|
2858 \section{The Multiple Precision Integer Library (MPI)} |
|
|
2859 The library comes with a copy of LibTomMath which is a multiple precision integer library written by the |
|
|
2860 author of LibTomCrypt. LibTomMath is a trivial to use ANSI C compatible large integer library which is free |
|
|
2861 for all uses and is distributed freely. |
|
|
2862 |
|
|
2863 At the heart of all the functions is the data type ``mp\_int'' (defined in tommath.h). This data type is what |
|
|
2864 will hold all large integers. In order to use an mp\_int one must initialize it first, for example: |
|
|
2865 \begin{verbatim} |
|
|
2866 #include <mycrypt.h> /* mycrypt.h includes mpi.h automatically */ |
|
|
2867 int main(void) |
|
|
2868 { |
|
|
2869 mp_int bignum; |
|
|
2870 |
|
|
2871 /* initialize it */ |
|
|
2872 mp_init(&bignum); |
|
|
2873 |
|
|
2874 return 0; |
|
|
2875 } |
|
|
2876 \end{verbatim} |
|
|
2877 If you are unfamiliar with the syntax of C the \& symbol is used to pass the address of ``bignum'' to the function. All |
|
|
2878 LibTomMath functions require the address of the parameters. To free the memory of a mp\_int use (for example): |
|
|
2879 \begin{verbatim} |
|
|
2880 mp_clear(&bignum); |
|
|
2881 \end{verbatim} |
|
|
2882 |
|
|
2883 The functions also have the basic form of one of the following: |
|
|
2884 \begin{verbatim} |
|
|
2885 mp_XXX(mp_int *a); |
|
|
2886 mp_XXX(mp_int *a, mp_int *b, mp_int *c); |
|
|
2887 mp_XXX(mp_int *a, mp_int *b, mp_int *c, mp_int *d); |
|
|
2888 \end{verbatim} |
|
|
2889 |
|
|
2890 Where they perform some operation and store the result in the mp\_int variable passed on the far right. |
|
|
2891 For example, to compute $c = a + b \mbox{ }(\mbox{mod }m)$ you would call: |
|
|
2892 \begin{verbatim} |
|
|
2893 mp_addmod(&a, &b, &m, &c); |
|
|
2894 \end{verbatim} |
|
|
2895 |
|
|
2896 \subsection{Binary Forms of ``mp\_int'' Variables} |
|
|
2897 |
|
|
2898 Often it is required to store a ``mp\_int'' in binary form for transport (e.g. exporting a key, packet |
|
|
2899 encryption, etc.). LibTomMath includes two functions to help when exporting numbers: |
|
|
2900 \begin{verbatim} |
|
|
2901 int mp_raw_size(mp_int *num); |
|
|
2902 mp_toraw(&num, buf); |
|
|
2903 \end{verbatim} |
|
|
2904 |
|
|
2905 The former function gives the size in bytes of the raw format and the latter function actually stores the raw data. All |
|
|
2906 ``mp\_int'' numbers are stored in big endian form (like PKCS demands) with the first byte being the sign of the number. The |
|
|
2907 ``rsa\_exptmod()'' function differs slightly since it will take the input in the form exactly as PKCS demands (without the |
|
|
2908 leading sign byte). All other functions include the sign byte (since its much simpler just to include it). The sign byte |
|
|
2909 must be zero for positive numbers and non-zero for negative numbers. For example, |
|
|
2910 the sequence: |
|
|
2911 \begin{verbatim} |
|
|
2912 00 FF 30 04 |
|
|
2913 \end{verbatim} |
|
|
2914 Represents the integer $255 \cdot 256^2 + 48 \cdot 256^1 + 4 \cdot 256^0$ or 16,723,972. |
|
|
2915 |
|
|
2916 To read a binary string back into a ``mp\_int'' call: |
|
|
2917 \begin{verbatim} |
|
|
2918 mp_read_raw(mp_int *num, unsigned char *str, int len); |
|
|
2919 \end{verbatim} |
|
|
2920 Where ``num'' is where to store it, ``str'' is the binary string (including the leading sign byte) and ``len'' is the |
|
|
2921 length of the binary string. |
|
|
2922 |
|
|
2923 \subsection{Primality Testing} |
|
|
2924 \index{Primality Testing} |
|
|
2925 The library includes primality testing and random prime functions as well. The primality tester will perform the test in |
|
|
2926 two phases. First it will perform trial division by the first few primes. Second it will perform eight rounds of the |
|
|
2927 Rabin-Miller primality testing algorithm. If the candidate passes both phases it is declared prime otherwise it is declared |
|
|
2928 composite. No prime number will fail the two phases but composites can. Each round of the Rabin-Miller algorithm reduces |
|
|
2929 the probability of a pseudo-prime by $1 \over 4$ therefore after sixteen rounds the probability is no more than |
|
|
2930 $\left ( { 1 \over 4 } \right )^{8} = 2^{-16}$. In practice the probability of error is in fact much lower than that. |
|
|
2931 |
|
|
2932 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}. |
|
|
2933 In essence a table of machine-word sized residues are kept of a candidate modulo a set of primes. When the candiate |
|
|
2934 is rejected and ultimately incremented to test the next number the residues are updated without using multi-word precision |
|
|
2935 math operations. As a result the routine can scan ahead to the next number required for testing with very little work |
|
|
2936 involved. |
|
|
2937 |
|
|
2938 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 |
|
|
2939 instance, in RSA two primes $p$ and $q$ are required. The order of the multiplicative sub-group (modulo $pq$) is given |
|
|
2940 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 |
|
|
2941 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 |
|
|
2942 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 |
|
|
2943 not equal to $(p - 1)(rs - 1)$. |
|
|
2944 |
|
|
2945 These are not technically part of the LibTomMath library but this is the best place to document them. |
|
|
2946 To test if a ``mp\_int'' is prime call: |
|
|
2947 \begin{verbatim} |
|
|
2948 int is_prime(mp_int *N, int *result); |
|
|
2949 \end{verbatim} |
|
|
2950 This puts a one in ``result'' if the number is probably prime, otherwise it places a zero in it. It is assumed that if |
|
|
2951 it returns an error that the value in ``result'' is undefined. To make |
|
|
2952 a random prime call: |
|
|
2953 \begin{verbatim} |
|
|
2954 int rand_prime(mp_int *N, unsigned long len, prng_state *prng, int wprng); |
|
|
2955 \end{verbatim} |
|
|
2956 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 |
|
|
2957 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 |
|
|
2958 ``len = -128'' to the function. Upon success it will return {\bf CRYPT\_OK} and ``N'' will contain an integer which |
|
|
2959 is very likely prime. |
|
|
2960 |
|
|
2961 \chapter{Programming Guidelines} |
|
|
2962 |
|
|
2963 \section{Secure Pseudo Random Number Generators} |
|
|
2964 Probably the singal most vulnerable point of any cryptosystem is the PRNG. Without one generating and protecting secrets |
|
|
2965 would be impossible. The requirement that one be setup correctly is vitally important and to address this point the library |
|
|
2966 does provide two RNG sources that will address the largest amount of end users as possible. The ``sprng'' PRNG provided |
|
|
2967 provides and easy to access source of entropy for any application on a *NIX or Windows computer. |
|
|
2968 |
|
|
2969 However, when the end user is not on one of these platforms the application developer must address the issue of finding |
|
|
2970 entropy. This manual is not designed to be a text on cryptography. I would just like to highlight that when you design |
|
|
2971 a cryptosystem make sure the first problem you solve is getting a fresh source of entropy. |
|
|
2972 |
|
|
2973 \section{Preventing Trivial Errors} |
|
|
2974 Two simple ways to prevent trivial errors is to prevent overflows and to check the return values. All of the functions |
|
|
2975 which output variable length strings will require you to pass the length of the destination. If the size of your output |
|
|
2976 buffer is smaller than the output it will report an error. Therefore, make sure the size you pass is correct! |
|
|
2977 |
|
|
2978 Also virtually all of the functions return an error code or {\bf CRYPT\_OK}. You should detect all errors as simple |
|
|
2979 typos or such can cause algorithms to fail to work as desired. |
|
|
2980 |
|
|
2981 \section{Registering Your Algorithms} |
|
|
2982 To avoid linking and other runtime errors it is important to register the ciphers, hashes and PRNGs you intend to use |
|
|
2983 before you try to use them. This includes any function which would use an algorithm indirectly through a descriptor table. |
|
|
2984 |
|
|
2985 A neat bonus to the registry system is that you can add external algorithms that are not part of the library without |
|
|
2986 having to hack the library. For example, suppose you have a hardware specific PRNG on your system. You could easily |
|
|
2987 write the few functions required plus a descriptor. After registering your PRNG all of the library functions that |
|
|
2988 need a PRNG can instantly take advantage of it. |
|
|
2989 |
|
|
2990 \section{Key Sizes} |
|
|
2991 |
|
|
2992 \subsection{Symmetric Ciphers} |
|
|
2993 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 |
|
|
2994 is not a hard thing todo. |
|
|
2995 |
|
|
2996 \subsection{Assymetric Ciphers} |
|
|
2997 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 |
|
|
2998 $n$ is estimated to be |
|
|
2999 \begin{equation} |
|
|
3000 e^{1.923 \cdot ln(n)^{1 \over 3} \cdot ln(ln(n))^{2 \over 3}} |
|
|
3001 \end{equation} |
|
|
3002 |
|
|
3003 Note that $n$ is not the bit-length but the magnitude. For example, for a 1024-bit key $n = 2^{1024}$. The work required |
|
|
3004 is: |
|
|
3005 \begin{center} |
|
|
3006 \begin{tabular}{|c|c|} |
|
|
3007 \hline RSA/DH Key Size (bits) & Work Factor ($log_2$) \\ |
|
|
3008 \hline 512 & 63.92 \\ |
|
|
3009 \hline 768 & 76.50 \\ |
|
|
3010 \hline 1024 & 86.76 \\ |
|
|
3011 \hline 1536 & 103.37 \\ |
|
|
3012 \hline 2048 & 116.88 \\ |
|
|
3013 \hline 2560 & 128.47 \\ |
|
|
3014 \hline 3072 & 138.73 \\ |
|
|
3015 \hline 4096 & 156.49 \\ |
|
|
3016 \hline |
|
|
3017 \end{tabular} |
|
|
3018 \end{center} |
|
|
3019 |
|
|
3020 The work factor for ECC keys is much higher since the best attack is still fully exponentional. Given a key of magnitude |
|
|
3021 $n$ it requires $\sqrt n$ work. The following table sumarizes the work required: |
|
|
3022 \begin{center} |
|
|
3023 \begin{tabular}{|c|c|} |
|
|
3024 \hline ECC Key Size (bits) & Work Factor ($log_2$) \\ |
|
|
3025 \hline 160 & 80 \\ |
|
|
3026 \hline 192 & 96 \\ |
|
|
3027 \hline 224 & 112 \\ |
|
|
3028 \hline 256 & 128 \\ |
|
|
3029 \hline 384 & 192 \\ |
|
|
3030 \hline 521 & 260.5 \\ |
|
|
3031 \hline |
|
|
3032 \end{tabular} |
|
|
3033 \end{center} |
|
|
3034 |
|
|
3035 Using the above tables the following suggestions for key sizes seems appropriate: |
|
|
3036 \begin{center} |
|
|
3037 \begin{tabular}{|c|c|c|} |
|
|
3038 \hline Security Goal & RSA/DH Key Size (bits) & ECC Key Size (bits) \\ |
|
|
3039 \hline Short term (less than a year) & 1024 & 160 \\ |
|
|
3040 \hline Short term (less than five years) & 1536 & 192 \\ |
|
|
3041 \hline Long Term (less than ten years) & 2560 & 256 \\ |
|
|
3042 \hline |
|
|
3043 \end{tabular} |
|
|
3044 \end{center} |
|
|
3045 |
|
|
3046 \section{Thread Safety} |
|
|
3047 The library is not thread safe but several simple precautions can be taken to avoid any problems. The registry functions |
|
|
3048 such as register\_cipher() are not thread safe no matter what you do. Its best to call them from your programs initializtion |
|
|
3049 code before threads are initiated. |
|
|
3050 |
|
|
3051 The rest of the code uses state variables you must pass it such as hash\_state, hmac\_state, etc. This means that if each |
|
|
3052 thread has its own state variables then they will not affect each other. This is fairly simple with symmetric ciphers |
|
|
3053 and hashes. However, the keyring and PRNG support is something the threads will want to share. The simplest workaround |
|
|
3054 is create semaphores or mutexes around calls to those functions. |
|
|
3055 |
|
|
3056 Since C does not have standard semaphores this support is not native to Libtomcrypt. Even a C based semaphore is not entire |
|
|
3057 possible as some compilers may ignore the ``volatile'' keyword or have multiple processors. Provide your host application |
|
|
3058 is modular enough putting the locks in the right place should not bloat the code significantly and will solve all thread |
|
|
3059 safety issues within the library. |
|
|
3060 |
|
|
3061 \chapter{Configuring the Library} |
|
|
3062 \section{Introduction} |
|
|
3063 The library is fairly flexible about how it can be built, used and generally distributed. Additions are being made with |
|
|
3064 each new release that will make the library even more flexible. Most options are placed in the makefile and others |
|
|
3065 are in ``mycrypt\_cfg.h''. All are used when the library is built from scratch. |
|
|
3066 |
|
|
3067 For GCC platforms the file ``makefile'' is the makefile to be used. On MSVC platforms ``makefile.vc'' and on PS2 platforms |
|
|
3068 ``makefile.ps2''. |
|
|
3069 |
|
|
3070 \section{mycrypt\_cfg.h} |
|
|
3071 The file ``mycrypt\_cfg.h'' is what lets you control what functionality you want to remove from the library. By default, |
|
|
3072 everything the library has to offer it built. |
|
|
3073 |
|
|
3074 \subsubsection{ARGTYPE} |
|
|
3075 This lets you control how the \_ARGCHK macro will behave. The macro is used to check pointers inside the functions against |
|
|
3076 NULL. There are three settings for ARGTYPE. When set to 0 it will have the default behaviour of printing a message to |
|
|
3077 stderr and raising a SIGABRT signal. This is provided so all platforms that use libtomcrypt can have an error that functions |
|
|
3078 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 |
|
|
3079 and no error checking will be performed. |
|
|
3080 |
|
|
3081 \subsubsection{Endianess} |
|
|
3082 There are five macros related to endianess issues. For little endian platforms define, ENDIAN\_LITTLE. For big endian |
|
|
3083 platforms define ENDIAN\_BIG. Similarly when the default word size of an ``unsigned long'' is 32-bits define ENDIAN\_32BITWORD |
|
|
3084 or define ENDIAN\_64BITWORD when its 64-bits. If you do not define any of them the library will automatically use ENDIAN\_NEUTRAL |
|
|
3085 which will work on all platforms. Currently the system will automatically detect GCC or MSVC on a windows platform as well |
|
|
3086 as GCC on a PS2 platform. |
|
|
3087 |
|
|
3088 \section{The Configure Script} |
|
|
3089 There are also options you can specify from the configure script or ``mycrypt\_config.h''. |
|
|
3090 |
|
|
3091 \subsubsection{X memory routines} |
|
|
3092 The makefiles must define three macros denoted as XMALLOC, XCALLOC and XFREE which resolve to the name of the respective |
|
|
3093 functions. This lets you substitute in your own memory routines. If you substitute in your own functions they must behave |
|
|
3094 like the standard C library functions in terms of what they expect as input and output. By default the library uses the |
|
|
3095 standard C routines. |
|
|
3096 |
|
|
3097 \subsubsection{X clock routines} |
|
|
3098 The rng\_get\_bytes() function can call a function that requires the clock() function. These macros let you override |
|
|
3099 the default clock() used with a replacement. By default the standard C library clock() function is used. |
|
|
3100 |
|
|
3101 \subsubsection{NO\_FILE} |
|
|
3102 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 |
|
|
3103 functions and instead simply return CRYPT\_ERROR. This should help resolve any linker errors stemming from a lack of |
|
|
3104 file I/O on embedded platforms. |
|
|
3105 |
|
|
3106 \subsubsection{CLEAN\_STACK} |
|
|
3107 When this functions is defined the functions that store key material on the stack will clean up afterwards. Assumes that |
|
|
3108 you have no memory paging with the stack. |
|
|
3109 |
|
|
3110 \subsubsection{Symmetric Ciphers, One-way Hashes, PRNGS and Public Key Functions} |
|
|
3111 There are a plethora of macros for the ciphers, hashes, PRNGs and public key functions which are fairly self-explanatory. |
|
|
3112 When they are defined the functionality is included otherwise it is not. There are some dependency issues which are |
|
|
3113 noted in the file. For instance, Yarrow requires CTR chaining mode, a block cipher and a hash function. |
|
|
3114 |
|
|
3115 \subsubsection{TWOFISH\_SMALL and TWOFISH\_TABLES} |
|
|
3116 Twofish is a 128-bit symmetric block cipher that is provided within the library. The cipher itself is flexible enough |
|
|
3117 to allow some tradeoffs in the implementation. When TWOFISH\_SMALL is defined the scheduled symmetric key for Twofish |
|
|
3118 requires only 200 bytes of memory. This is achieved by not pre-computing the substitution boxes. Having this |
|
|
3119 defined will also greatly slow down the cipher. When this macro is not defined Twofish will pre-compute the |
|
|
3120 tables at a cost of 4KB of memory. The cipher will be much faster as a result. |
|
|
3121 |
|
|
3122 When TWOFISH\_TABLES is defined the cipher will use pre-computed (and fixed in code) tables required to work. This is |
|
|
3123 useful when TWOFISH\_SMALL is defined as the table values are computed on the fly. When this is defined the code size |
|
|
3124 will increase by approximately 500 bytes. If this is defined but TWOFISH\_SMALL is not the cipher will still work but |
|
|
3125 it will not speed up the encryption or decryption functions. |
|
|
3126 |
|
|
3127 \subsubsection{SMALL\_CODE} |
|
|
3128 When this is defined some of the code such as the Rijndael and SAFER+ ciphers are replaced with smaller code variants. |
|
|
3129 These variants are slower but can save quite a bit of code space. |
|
|
3130 |
|
15
|
3131 \input{crypt.ind} |
|
|
3132 |
|
3
|
3133 \end{document} |
