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