nettle.texinfo 37.5 KB
Newer Older
Niels Möller's avatar
Niels Möller committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
\input texinfo          @c -*-texinfo-*-

@c %**start of header
@setfilename nettle.info
@settitle The Nettle low-level cryptographic library.
@c %**end of header

@syncodeindex fn cp

@dircategory GNU Libraries
@direntry
* Nettle: (nettle).           A low-level cryptographics library.
@end direntry

15
@set UPDATED-FOR 1.0
Niels Möller's avatar
Niels Möller committed
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

@c Latin-1 doesn't work with tex output.
@c Also lookout for é characters.

@set AUTHOR Niels Möller
@ifinfo
Draft manual for the Nettle library. This manual corresponds to version
@value{UPDATED-FOR}.

Copyright 2001 @value{AUTHOR}

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

@end ifinfo

@titlepage
@sp 10
@c @center @titlefont{Nettle Manual}

@title Nettle Manual
@subtitle For the Nettle Library version @value{UPDATED-FOR}

@author @value{AUTHOR}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001 @value{AUTHOR}

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

@end titlepage

91
92
@contents

Niels Möller's avatar
Niels Möller committed
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@ifnottex
@node     Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top

This document describes the nettle low-level cryptographic library. You
can use the library directly from your C-programs, or (recommended)
write or use an object-oriented wrapper for your favourite language or
application.

This manual coresponds to version @value{UPDATED-FOR} of the library.

@menu
* Introduction::                
* Copyright::                   
* Conventions::                 
* Example::                     
* Reference::                   
* Installation::                
* Index::                       
@end menu

@end ifnottex

@node Introduction, Copyright, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

Nettle is a cryptographic library that is designed to fit easily in more
or less any context: In crypto toolkits for object-oriented languages
(C++, Python, Pike, ...), in applications like LSH or GNUPG, or even in
kernel space. In most contexts, you need more than the basic
cryptographic algorithms, you also need some way to keep track of available
algorithms, their properties and variants. You often have some algorithm
selection process, often dictated by a protocol you want to implement.

129
And as the requirements of applications differ in subtle and not so
Niels Möller's avatar
Niels Möller committed
130
131
132
133
134
135
136
137
138
139
subtle ways, an API that fits one application well can be a pain to use
in a different context. And that is why there are so many different
cryptographic libraries around.

Nettle tries to avoid this problem by doing one thing, the low-level
crypto stuff, and providing a @emph{simple} but general interface to it.
In particular, Nettle doesn't do algorithm selection. It doesn't do
memory allocation. It doesn't do any I/O.

The idea is that one can build several application and context specific
140
interfaces on top of Nettle, and share the code, testcases, benchmarks,
Niels Möller's avatar
Niels Möller committed
141
142
143
144
documentation, etc. For this first version, the only application using
Nettle is LSH, and it uses an object-oriented abstraction on top of the
library. 

145
146
147
148
This manual explains how to use the Nettle library. It also tries to
provide some background on the cryptography, and advice on how to best
put it to use.

Niels Möller's avatar
Niels Möller committed
149
150
151
152
@node Copyright, Conventions, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Copyright

153
154
155
156
157
158
159
160
Nettle is distributed under the GNU General Public License (GPL) (see
the file COPYING for details). However, most of the individual files
are dual licensed under less restrictive licenses like the GNU Lesser
General Public License (LGPL), or are in the public domain. This means
that if you don't use the parts of nettle that are GPL-only, you have
the option to use the Nettle library just as if it were licensed under
the LGPL. To find the current status of particular files, you have to
read the copyright notices at the top of the files.
Niels Möller's avatar
Niels Möller committed
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

A list of the supported algorithms, their origins and licenses:

@table @emph
@item AES
The implementation of the AES cipher (also known as rijndael) is written
by Rafael Sevilla. Released under the LGPL.

@item ARCFOUR
The implementation of the ARCFOUR (also known as RC4) cipher is written
by Niels Möller. Released under the LGPL.

@item BLOWFISH
The implementation of the BLOWFISH cipher is written by Werner Koch,
copyright owned by the Free Software Foundation. Also hacked by Ray
Dassen and Niels Möller. Released under the GPL.

@item CAST128
The implementation of the CAST128 cipher is written by Steve Reid.
Released into the public domain.

@item DES
The implementation of the DES cipher is written by Dana L. How, and
released under the LGPL.

@item MD5
The implementation of the MD5 message digest is written by Colin Plumb.
It has been hacked some more by Andrew Kuchling and Niels Möller.
Released into the public domain.

@item SERPENT
The implementation of the SERPENT cipher is written by Ross Anderson,
Eli Biham, and Lars Knudsen, adapted to LSH by Rafael Sevilla, and to
194
Nettle by Niels Möller. Released under the GPL.
Niels Möller's avatar
Niels Möller committed
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211

@item SHA1
The implementation of the SHA1 message digest is written by Peter
Gutmann, and hacked some more by Andrew Kuchling and Niels Möller.
Released into the public domain.

@item TWOFISH
The implementation of the TWOFISH cipher is written by Ruud de Rooij.
Released under the LGPL.
@end table

@node Conventions, Example, Copyright, Top
@comment  node-name,  next,  previous,  up
@chapter Conventions

For each supported algorithm, there is an include file that defines a
@emph{context struct}, a few constants, and declares functions for
212
operating on the context. The context struct encapsulates all information
Niels Möller's avatar
Niels Möller committed
213
214
215
needed by the algorithm, and it can be copied or moved in memory with no
unexpected effects.

216
217
218
219
220
221
222
223
For consistency, functions for different algorithms are very similar,
but there are some differences, for instance reflecting if the key setup
or encryption function differ for encryption and encryption, and whether
or not key setup can fail. There are also differences between algorithms
that don't show in function prototypes, but which the application must
nevertheless be aware of. There is no big difference between the
functions for stream ciphers and for block ciphers, although they should
be used quite differently by the application.
Niels Möller's avatar
Niels Möller committed
224
225
226
227
228
229
230
231
232
233
234

If your application uses more than one algorithm, you should probably
create an interface that is tailor-made for your needs, and then write a
few lines of glue code on top of Nettle.

By convention, for an algorithm named @code{foo}, the struct tag for the
context struct is @code{foo_ctx}, constants and functions uses prefixes
like @code{FOO_BLOCK_SIZE} (a constant) and @code{foo_set_key} (a
function).

In all functions, strings are represented with an explicit length, of
235
type @code{unsigned}, and a pointer of type @code{uint8_t *} or
Niels Möller's avatar
Niels Möller committed
236
237
238
239
@code{const uint8_t *}. For functions that transform one string to
another, the argument order is length, destination pointer and source
pointer. Source and destination areas are of the same length. Source and
destination may be the same, so that you can process strings in place,
240
but they @emph{must not} overlap in any other way.
Niels Möller's avatar
Niels Möller committed
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305

@node Example, Reference, Conventions, Top
@comment  node-name,  next,  previous,  up
@chapter Example

A simple example program that reads a file from standard in and writes
its SHA1 checksum on stdout should give the flavour of Nettle.

@example
/* FIXME: This code is untested. */
#include <stdio.h>
#include <stdlib.h>

#include <nettle/sha1.h>

#define BUF_SIZE 1000

static void
display_hex(unsigned length, uint8_t *data)
@{
  static const char digits[16] = "0123456789abcdef";
  unsigned i;

  for (i = 0; i<length; i++)
  @{
    uint8_t byte = data[i];
    printf("%c%c ", digits[(byte / 16) & 0xf], digits[byte & 0xf]);
  @}
@}

int
main(int argc, char **argv)
@{
  struct sha1_ctx ctx;
  uint8_t buffer[BUF_SIZE];
  uint8_t digest[SHA1_DIGEST_SIZE];
  
  sha1_init(&ctx);
  for (;;)
  @{
    int done = fread(buffer, 1, sizeof(buffer), stdin);
    if (done <= 0)
      break;
    sha1_update(&ctx, done, buf);
  @}
  if (ferror(stdin))
    return EXIT_FAILURE;

  sha1_finish(&ctx);
  sha1_digest(&ctx, SHA1_DIGEST_SIZE, digest);

  display_hex(SHA1_DIGEST_SIZE, digest);
  return EXIT_SUCCESS;  
@}
@end example

@node Reference, Installation, Example, Top
@comment  node-name,  next,  previous,  up
@chapter Reference

This chapter describes all the Nettle functions, grouped by family.

@menu
* Hash functions::              
* Cipher functions::            
306
* Cipher Block Chaining::       
Niels Möller's avatar
Niels Möller committed
307
* Miscellaneous functions::     
308
* Compatibility functions::     
Niels Möller's avatar
Niels Möller committed
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
@end menu

@node Hash functions, Cipher functions, Reference, Reference
@comment  node-name,  next,  previous,  up
@section Hash functions

A cryptographic @dfn{hash function} is a function that takes variable
size strings, and maps them to strings of fixed, short, length. There
are naturally lots of collisions, as there are more possible 1MB files
than 20 byte strings. But the function is constructed such that is hard
to find the collisions. More precisely, a cryptographic hash function
@code{H} should have the following properties:

@table @emph

@item One-way
Given a hash value @code{H(x)} it is hard to find a string @code{x}
that hashes to that value.

@item Collision-resistant
It is hard to find two different strings, @code{x} and @code{y}, such
that @code{H(x)} = @code{H(y)}.

@end table

Hash functions are useful as building blocks for digital signatures,
335
message authentication codes, pseudo random generators, association of
Niels Möller's avatar
Niels Möller committed
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
unique id:s to documents, and many other things.

@subsection @acronym{MD5}

MD5 is a message digest function constructed by Ronald Rivest, and
described in @cite{RFC 1321}. It outputs message digests of 128 bits, or
16 octets. Nettle defines MD5 in @file{<nettle/md5.h>}.

@deftp {Context struct} {struct md5_ctx}
@end deftp

@defvr Constant MD5_DIGEST_SIZE
The size of an MD5 digest, i.e. 16.
@end defvr

@defvr Constant MD5_DATA_SIZE
The internal block size of MD5. Useful for some special constructions,
in particular HMAC-MD5.
@end defvr

@deftypefun void md5_init (struct md5_ctx *@var{ctx})
Initialize the MD5 state.
@end deftypefun

@deftypefun void md5_update (struct md5_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
Hash some more data.
@end deftypefun

@deftypefun void md5_final (struct md5_ctx *@var{ctx})
Performs final processing that is needed after all input data has been
processed with @code{md5_update}.
@end deftypefun

@deftypefun void md5_digest (struct md5_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
370
371
372
Extracts the message digest, writing it to @var{digest}. @var{length}
may be smaller than @code{MD5_DIGEST_SIZE}, in which case only the first
@var{length} octets of the digest are written.
Niels Möller's avatar
Niels Möller committed
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423

This functions doesn't change the state in any way.
@end deftypefun

The normal way to use MD5 is to call the functions in order: First
@code{md5_init}, then @code{md5_update} zero or more times, then
@code{md5_final}, and at last @code{md5_digest} zero or more times.

To start over, you can call @code{md5_init} at any time.

@subsection @acronym{SHA1}

SHA1 is a hash function specified by @dfn{NIST} (The U.S. National Institute
for Standards and Technology. It outputs hash values of 160 bits, or 20
octets. Nettle defines SHA1 in @file{<nettle/sha1.h>}.

The functions are analogous to the MD5 ones.

@deftp {Context struct} {struct sha1_ctx}
@end deftp

@defvr Constant SHA1_DIGEST_SIZE
The size of an SHA1 digest, i.e. 20.
@end defvr

@defvr Constant SHA1_DATA_SIZE
The internal block size of SHA1. Useful for some special constructions,
in particular HMAC-SHA1.
@end defvr

@deftypefun void sha1_init (struct sha1_ctx *@var{ctx})
Initialize the SHA1 state.
@end deftypefun

@deftypefun void sha1_update (struct sha1_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
Hash some more data.
@end deftypefun

@deftypefun void sha1_final (struct sha1_ctx *@var{ctx})
Performs final processing that is needed after all input data has been
processed with @code{sha1_update}.
@end deftypefun

@deftypefun void sha1_digest (struct sha1_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
Extracts the digest, writing it to @var{digest}. @var{length} may be smaller than
@code{SHA1_DIGEST_SIZE}, in which case only the first @var{length} octets
of the digest are written.

This functions doesn't change the state in any way.
@end deftypefun

424
@node Cipher functions, Cipher Block Chaining, Hash functions, Reference
Niels Möller's avatar
Niels Möller committed
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
@comment  node-name,  next,  previous,  up
@section Cipher functions

A @dfn{cipher} is a function that takes a message or @dfn{plaintext}
and a secret @dfn{key} and transforms it to a @dfn{ciphertext}. Given
only the ciphertext, but not the key, it should be hard to find the
cleartext. Given matching pairs of plaintext and ciphertext, it should
be hard to find the key.

There are two main classes of ciphers: Block ciphers and stream ciphers.

A block cipher can process data only in fixed size chunks, called
@dfn{blocks}. Typical block sizes are 8 or 16 octets. To encrypt
arbitrary messages, you usually have to pad it to an integral number of
blocks, split it into blocks, and then process each block. The simplest
way is to process one block at a time, independent of each other. That
mode of operation is called @dfn{ECB}, Electronic Code Book mode.
However, using ECB is usually a bad idea. For a start, plaintext blocks
that are equal are transformed to ciphertext blocks that are equal; that
leaks information about the plaintext. Usually you should apply the
cipher is some feedback mode, @dfn{CBC} (Cipher Block Chaining) being one
446
447
of the most popular. @xref{Cipher Block Chaining}, for information on
how to apply CBC with Nettle.
Niels Möller's avatar
Niels Möller committed
448
449
450
451
452
453
454
455
456
457
458
459
460

A stream cipher can be used for messages of arbitrary length; a typical
stream cipher is a keyed pseudorandom generator. To encrypt a plaintext
message of @var{n} octets, you key the generator, generate @var{n}
octets of pseudorandom data, and XOR it with the plaintext. To decrypt,
regenerate the same stream using the key, XOR it to the ciphertext, and
the plaintext is recovered.

@strong{Caution:} The first rule for this kind of cipher is the
same as for a One Time Pad: @emph{never} ever use the same key twice.

A common misconception is that encryption, by itself, implies
authentication. Say that you and a friend share a secret key, and you
461
462
463
receive an encrypted message. You apply the key, and get a cleartext
message that makes sense to you. Can you then be sure that it really was
your friend that wrote the message you're reading? The anser is no. For
Niels Möller's avatar
Niels Möller committed
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
example, if you were using a block cipher in ECB mode, an attacker may
pick up the message on its way, and reorder, delete or repeat some of
the blocks. Even if the attacker can't decrypt the message, he can
change it so that you are not reading the same message as your friend
wrote. If you are using a block cipher in CBC mode rather than ECB, or
are using a stream cipher, the possibilities for this sort of attack are
different, but the attacker can still make predictable changes to the
message.

It is recommended to @emph{always} use an authentication mechanism in
addition to encrypting the messages. Popular choices are Message
Authetication Codes like HMAC-SHA1, or digital signatures.

Some ciphers have so called "weak keys", keys that results in
undesirable structure after the key setup processing, and should be
avoided. In Nettle, the presence of weak keys for a cipher mean that the
key setup function can fail, so you have to check its return value. In
addition, the context struct has a field @code{status}, that is set to a
non-zero value if key setup fails. When possible, avoid algorithm that
have weak keys. There are several good ciphers that don't have any weak
keys.

486
487
488
489
490
491
492
493
To encrypt a message, you first initialize a cipher context for
encryption or decryption with a particular key. You then use the context
to process plaintext or ciphertext messages. The initialization is known
as called @dfn{key setup}. With Nettle, it is recommended to use each
context struct for only one direction, even if some of the ciphers use a
single key setup function that can be used for both encryption and
decryption.

Niels Möller's avatar
Niels Möller committed
494
495
@subsection AES
AES is a quite new block cipher, specified by NIST as a replacement for
496
497
498
the older DES standard. The standarad is the result of a competition
between cipher designers. The winning design, also known as RIJNDAEL,
was constructed by Joan Daemen and Vincent Rijnmen.
Niels Möller's avatar
Niels Möller committed
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596

Like all the AES candidates, the winning design uses a block size of 128
bits, or 16 octets, and variable keysize, 128, 192 and 256 bits (16, 24
and 32 octets) being the allowed key sizes. It does not have any weak
keys. Nettle defines AES in @file{<nettle/aes.h>}.
 
@deftp {Context struct} {struct aes_ctx}
@end deftp

@defvr Constant AES_BLOCK_SIZE
The AES blocksize, 16
@end defvr

@defvr Constant AES_MIN_KEY_SIZE
@end defvr

@defvr Constant AES_MAX_KEY_SIZE
@end defvr

@defvr Constant AES_KEY_SIZE
Default AES key size, 32
@end defvr

@deftypefun void aes_set_key (struct aes_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and
decryption. 
@end deftypefun

@deftypefun void aes_encrypt (struct aes_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Encryption function. @var{length} must be an integral multiple of the
block size. If it is more than one block, the data is processed in ECB
mode. @code{src} and @code{dst} may be equal, but they must not overlap
in any other way.
@end deftypefun

@deftypefun void aes_decrypt (struct aes_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Analogous to @code{aes_encrypt}
@end deftypefun

@subsection ARCFOUR
ARCFOUR is a stream cipher, also known under the trade marked name RC4,
and it is one of the fastest ciphers around. A problem is that the key
setup of ARCFOUR is quite weak, you should never use keys with
structure, keys that are ordinary passwords, or sequences of keys like
"secret:1", "secret:2", @enddots{}. If you have keys that don't look
like random bit strings, and you want to use ARCFOUR, always hash the
key before feeding it to ARCFOUR. For example

@example
/* A more robust key setup function for ARCFOUR */
void
my_arcfour_set_key(struct arcfour_ctx *ctx,
                   unsigned length, const uint8_t *key)
@{
  struct sha1_ctx hash;
  uint8_t digest[SHA1_DIGEST_SIZE];

  sha1_init(&hash);
  sha1_update(&hash, length, key);
  sha1_final(&hash);
  sha1_digest(&hash, SHA1_DIGEST_SIZE, digest);

  arcfour_set_key(ctx, SHA1_DIGEST_SIZE, digest);
@}
@end example

Nettle defines ARCFOUR in @file{<nettle/arcfour.h>}.

@deftp {Context struct} {struct arcfour_ctx}
@end deftp

@defvr Constant ARCFOUR_MIN_KEY_SIZE
Minimum key size, 1
@end defvr

@defvr Constant ARCFOUR_MAX_KEY_SIZE
Maximum key size, 256
@end defvr

@defvr Constant ARCFOUR_KEY_SIZE
Default ARCFOUR key size, 16
@end defvr

@deftypefun void arcfour_set_key (struct arcfour_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and
decryption. 
@end deftypefun

@deftypefun void arcfour_crypt (struct arcfour_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
Encrypt some data. The same function is used for both encryption and
decryption. Unlike the block ciphers, this function modifies the
context, so you can split the data into arbitrary chunks and encrypt
them one after another. The result is the same as if you had called
@code{arcfour_crypt} only once with all the data.
@end deftypefun

@subsection CAST128

597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
CAST-128 is a block cipher, specified in @cite{RFC 2144}. It uses a 64
bit (8 octets) block size, and a variable key size of up to 128 bits.
Nettle defines cast128 in @file{<nettle/cast128.h>}.

@deftp {Context struct} {struct cast128_ctx}
@end deftp

@defvr Constant CAST128_BLOCK_SIZE
The CAST128 blocksize, 8
@end defvr

@defvr Constant CAST128_MIN_KEY_SIZE
Minumim CAST128 key size, 5
@end defvr

@defvr Constant CAST128_MAX_KEY_SIZE
Maximum CAST128 key size, 16
@end defvr

@defvr Constant CAST128_KEY_SIZE
Default CAST128 key size, 16
@end defvr

@deftypefun void cast128_set_key (struct cast128_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and
decryption. 
@end deftypefun

@deftypefun void cast128_encrypt (struct cast128_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Encryption function. @var{length} must be an integral multiple of the
block size. If it is more than one block, the data is processed in ECB
mode. @code{src} and @code{dst} may be equal, but they must not overlap
in any other way.
@end deftypefun

@deftypefun void cast128_decrypt (struct cast128_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Analogous to @code{cast128_encrypt}
@end deftypefun

Niels Möller's avatar
Niels Möller committed
636
637
@subsection BLOWFISH

638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block
size of 64 bits (8 octets), and a variable key size, up to 448 bits. It
has some weak keys. Nettle defines BLOWFISH in @file{<nettle/blowfish.h>}.

@deftp {Context struct} {struct blowfish_ctx}
@end deftp

@defvr Constant BLOWFISH_BLOCK_SIZE
The BLOWFISH blocksize, 8
@end defvr

@defvr Constant BLOWFISH_MIN_KEY_SIZE
Minimum BLOWFISH key size, 8
@end defvr

@defvr Constant BLOWFISH_MAX_KEY_SIZE
Maximum BLOWFISH key size, 56
@end defvr

@defvr Constant BLOWFISH_KEY_SIZE
Default BLOWFISH key size, 16
@end defvr

@deftypefun int blowfish_set_key (struct blowfish_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and
decryption. Returns 1 on success, and 0 if the key was weak. Calling
@code{blowfish_encrypt} or @code{blowfish_decrypt} with a weak key will
crash with an assert violation.
@end deftypefun

@deftypefun void blowfish_encrypt (struct blowfish_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Encryption function. @var{length} must be an integral multiple of the
block size. If it is more than one block, the data is processed in ECB
mode. @code{src} and @code{dst} may be equal, but they must not overlap
in any other way.
@end deftypefun

@deftypefun void blowfish_decrypt (struct blowfish_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Analogous to @code{blowfish_encrypt}
@end deftypefun

Niels Möller's avatar
Niels Möller committed
679
@subsection DES
680
681
682
683
684
685
686
687
688
689
690
DES is the old Data Encryption Standard, specified by NIST. It uses a
block size of 64 bits (8 octets), and a key size of 56 bits. However,
the key bits are distributed over 8 octets, where the least significant
bit of each octet is used for parity. A common way to use DES is to
generate 8 random octets in some way, then set the least significant bit
of each octet to get odd parity, and initialize DES with the resulting
key.

The key size of DES is so small that keys can be found by brute force,
using specialized hardware or lots of ordinary work stations in
parallell. One shouldn't be using plain DES at all today, if one uses
691
DES at all one should be using DES3 or "triple DES", see below.
692
693
694
695
696
697
698
699
700
701
702
703
704
705

DES also has some weak keys. Nettle defines DES in @file{<nettle/des.h>}.

@deftp {Context struct} {struct des_ctx}
@end deftp

@defvr Constant DES_BLOCK_SIZE
The DES blocksize, 8
@end defvr

@defvr Constant DES_KEY_SIZE
DES key size, 8
@end defvr

706
@deftypefun int des_set_key (struct des_ctx *@var{ctx}, const uint8_t *@var{key})
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
Initialize the cipher. The same function is used for both encryption and
decryption. Returns 1 on success, and 0 if the key was weak or had bad
parity. Calling @code{des_encrypt} or @code{des_decrypt} with a bad key
will crash with an assert violation.
@end deftypefun

@deftypefun void des_encrypt (struct des_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Encryption function. @var{length} must be an integral multiple of the
block size. If it is more than one block, the data is processed in ECB
mode. @code{src} and @code{dst} may be equal, but they must not overlap
in any other way.
@end deftypefun

@deftypefun void des_decrypt (struct des_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Analogous to @code{des_encrypt}
@end deftypefun
Niels Möller's avatar
Niels Möller committed
723

724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
@deftypefun void des_fix_parity (unsigned @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
Adjusts the parity bits to match DES's requirements. You need this
function if you have created a random-looking string by a key agreement
protocol, and want to use it as a DES key. @var{dst} and @var{src} may
be equal.
@end deftypefun

@subsection DES3
The inadequate key size of DES has already been mentioned. One way to
increase the key size is to pipe together several DES boxes with
independent keys. It turns out that using two DES ciphers is not as
secure as one might think, even if the key size of the combination is a
respectable 112 bits.

The standard way to increase DES's key size is to use three DES boxes.
The mode of operation is a little peculiar: the middle DES box is wired
in the reverse direction. To encrypt a block with DES3, you encrypt it
using the first 56 bits of the key, then @emph{decrypt} it using the
middle 56 bits of the key, and finally encrypt it again using the last
56 bits of the key. This is known as "ede" triple-DES, for
"encrypt-decrypt-encrypt".

The "ede" construction provides some backward compatibility, as you get
plain single DES simply by feeding the same key to all three boxes. That
should help keeping down the gate count, and the price, of hardware
circuits implementing both plain DES and DES3.

DES3 has a key size of 168 bits, but just like plain DES, useless parity
bits are inserted, so that keys are represented as 24 octets (192 bits).
As a 112 bit key is large enough to make brute force attacks
impractical, some applications uses a "two-key" variant of triple-DES.
In this mode, the same key bits are used for the first and the last DES
box in the pipe, while the middle box is keyed independently. The
two-key variant is believed to be secure, i.e. there are no known
attacks significantly better than brute force.

Naturally, it's simple to implement triple-DES on top of Nettle's DES
functions. Nettle includes an inplementation of three-key "ede"
triple-DES, it is defined in the same place as plain DES,
@file{<nettle/des.h>}.

@deftp {Context struct} {struct des3_ctx}
@end deftp

@defvr Constant DES3_BLOCK_SIZE
The DES3 blocksize is the same as DES_BLOCK_SIZE, 8
@end defvr

@defvr Constant DES3_KEY_SIZE
DES key size, 24
@end defvr

@deftypefun int des3_set_key (struct des3_ctx *@var{ctx}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and
decryption. Returns 1 on success, and 0 if the key was weak or had bad
parity. Calling @code{des_encrypt} or @code{des_decrypt} with a bad key
will crash with an assert violation.
@end deftypefun

For random-looking strings, you can use @code{des_fix_parity} to adjust
the parity bits before calling @code{des3_set_key}.

@deftypefun void des3_encrypt (struct des3_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Encryption function. @var{length} must be an integral multiple of the
block size. If it is more than one block, the data is processed in ECB
mode. @code{src} and @code{dst} may be equal, but they must not overlap
in any other way.
@end deftypefun

@deftypefun void des3_decrypt (struct des3_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Analogous to @code{des_encrypt}
@end deftypefun

Niels Möller's avatar
Niels Möller committed
797
@subsection SERPENT
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
SERPENT is one of the AES finalists, designed by Ross Anderson, Eli
Biham and Lars Knudsen. Thus, the interface and properties are similar
to AES'. One pecularity is that it is quite pointless to use it with
anything but the maximum key size, smaller keys are just padded to
larger ones. Nettle defines SERPENT in @file{<nettle/serpent.h>}.

@deftp {Context struct} {struct serpent_ctx}
@end deftp

@defvr Constant SERPENT_BLOCK_SIZE
The SERPENT blocksize, 16
@end defvr

@defvr Constant SERPENT_MIN_KEY_SIZE
Minumim SERPENT key size, 16
@end defvr

@defvr Constant SERPENT_MAX_KEY_SIZE
Maximum SERPENT key size, 32
@end defvr

@defvr Constant SERPENT_KEY_SIZE
Default SERPENT key size, 32
@end defvr

@deftypefun void serpent_set_key (struct serpent_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and
decryption. 
@end deftypefun

@deftypefun void serpent_encrypt (struct serpent_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Encryption function. @var{length} must be an integral multiple of the
block size. If it is more than one block, the data is processed in ECB
mode. @code{src} and @code{dst} may be equal, but they must not overlap
in any other way.
@end deftypefun

@deftypefun void serpent_decrypt (struct serpent_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Analogous to @code{serpent_encrypt}
@end deftypefun

Niels Möller's avatar
Niels Möller committed
839
840

@subsection TWOFISH
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
Another AES finalist, this one designed by Bruce Schneier and others.
Nettle defines it in @file{<nettle/twofish.h>}.

@deftp {Context struct} {struct twofish_ctx}
@end deftp

@defvr Constant TWOFISH_BLOCK_SIZE
The TWOFISH blocksize, 16
@end defvr

@defvr Constant TWOFISH_MIN_KEY_SIZE
Minumim TWOFISH key size, 16
@end defvr

@defvr Constant TWOFISH_MAX_KEY_SIZE
Maximum TWOFISH key size, 32
@end defvr

@defvr Constant TWOFISH_KEY_SIZE
Default TWOFISH key size, 32
@end defvr

@deftypefun void twofish_set_key (struct twofish_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
Initialize the cipher. The same function is used for both encryption and
decryption. 
@end deftypefun

@deftypefun void twofish_encrypt (struct twofish_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Encryption function. @var{length} must be an integral multiple of the
block size. If it is more than one block, the data is processed in ECB
mode. @code{src} and @code{dst} may be equal, but they must not overlap
in any other way.
@end deftypefun

@deftypefun void twofish_decrypt (struct twofish_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{dst}, uint8_t *@var{src})
Analogous to @code{twofish_encrypt}
@end deftypefun

879
@node Cipher Block Chaining, Miscellaneous functions, Cipher functions, Reference
880
881
882
@comment  node-name,  next,  previous,  up
@section Cipher Block Chaining

883
When using CBC mode, cleartext blocks are not encrypted independently of
884
each other, like in Electronic Cook Book mode. Instead, when encrypting a
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
block in CBC mode, the previous ciphertext block is XOR:ed with the
cleartext before it is fed to the block cipher. When encrypting the
first block, a random block called an @dfn{IV}, or Initialization
Vector, is used as the ``previous ciphertext block''. The IV should be
chosen randomly, but it need not be kept secret, and can even be
transmitted in the clear together with the encrypted data.

In symbols, if @code{E_k} is the encryption function of a blockcipher,
and @code{IV} is the initialization vector, then @code{n} cleartext blocks
@code{M_1},@dots{} @code{M_n} are transformed into @code{n} ciphertext blocks
@code{C_1},@dots{} @code{C_n} as follows:

@example
C_1 = E_k(IV  XOR M_1)
C_2 = E_k(C_1 XOR M_2)

@dots{}

C_n = E_k(C_(n-1) XOR M_n)
@end example

906
907
908
909
910
911
912
913
Nettle includes a few utility functions for applying a block cipher in
Cipher Block Chaining (CBC) mode. The functions uses @code{void *} to
pass cipher contexts around.

@deftypefun {void} cbc_encrypt (void *@var{ctx}, void (*@var{f})(), unsigned @var{block_size}, uint8_t *@var{iv}, unsigned @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
@deftypefunx {void} cbc_decrypt (void *@var{ctx}, void (*@var{f})(), unsigned @var{block_size}, uint8_t *@var{iv}, unsigned @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})

Applies the encryption or decryption function @var{f} in CBC mde. The
914
915
916
917
918
919
920
921
function @var{f} is really typed as

@code{void f (void *@var{ctx}, unsigned @var{length}, uint8_t @var{dst},
const uint8_t *@var{src})},

@noindent and the @code{cbc_encrypt} and @code{cbc_decrypt} functions pass their
argument @var{ctx} on to @var{f}.
@end deftypefun
922

923
There are also some macros to help use these functions correctly.
924

925
@deffn Macro CBC_CTX (@var{context_type}, @var{block_size})
926
927
928
929
930
931
932
Expands into
@example
@{
   context_type ctx;
   uint8_t iv[block_size];
@}
@end example
933
934
@end deffn

935
It can be used to define a CBC context struct, either directly,
936

937
938
939
940
941
942
943
944
945
946
@example
struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;
@end example

or to give it a struct tag,

@example
struct aes_cbc_ctx CBC_CTX (struct aes_ctx, AES_BLOCK_SIZE);
@end example

947
@deffn Macro CBC_SET_IV (@var{ctx}, @var{iv})
948
First argument is a pointer to a context struct as defined by @code{CBC_CTX},
949
950
951
and the second is a pointer to an Initialization Vector (IV) that is
copied into that context.
@end deffn
952
953
954

@deffn Macro CBC_ENCRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src})
@deffnx Macro CBC_DECRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src})
955
956
957
958
959
A simpler way to invoke @code{cbc_encrypt} and @code{cbc_decrypt}. The
first argument is a pointer to a context struct as defined by
@code{CBC_CTX}, and the second argument is an encryption or decryption
function following Nettle's conventions. The last three arguments define
the source and destination area for the operation.
960
@end deffn
961

962
963
964
These macros use some tricks to make the compiler display a warning if
the types of @var{f} and @var{ctx} don't match, e.g. if you try to use
an @code{struct aes_ctx} context with the @code{des_encrypt} function.
965

Niels Möller's avatar
Niels Möller committed
966

967
@node Miscellaneous functions, Compatibility functions, Cipher Block Chaining, Reference
Niels Möller's avatar
Niels Möller committed
968
969
970
@comment  node-name,  next,  previous,  up
@section Miscellaneous functions

971
972
973
974
975
976
@deftypefun {uint8_t *} memxor (uint8_t *@var{dst}, const uint8_t *@var{src}, size_t @var{n})
XOR:s the source area on top of the destination area. The interface
doesn't follow the Nettle conventions, because it is intended to be
similar to the ANSI-C @code{memcpy} function.
@end deftypefun

977
978
@code{memxor} is declared in @file{<nettle/memxor.h>}.

979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
@node Compatibility functions,  , Miscellaneous functions, Reference
@comment  node-name,  next,  previous,  up
@section Compatibility functions

For convenience, Nettle includes alternative interfaces to some
algorithms, for compatibilty with some other popular crypto toolkits.
These are not fully documented here; refer to the source or to the
documentation for the original implementation.

MD5 is defined in [RFCXXX], which includes a reference implementation.
Nettle defines a compatible interface to MD5 in
@file{<nettle/md5-compat.h>}. This file defines the typedef
@code{MD5_CTX}, and declares the functions @code{MD5Init}, @code{MD5Update} and
@code{MD5Final}.

Eric Young's "libdes" (also part of OpenSSL) is a quite popular DES
implementation. Nettle includes a subset if it's interface in
@file{<nettle/des-compat.h>}. This file defines the typedefs
@code{des_key_schedule} and @code{des_cblock}, two constants
@code{DES_ENCRYPT} and @code{DES_DECRYPT}, and declares one global
variable @code{des_check_key}, and the functions @code{des_cbc_cksum}
@code{des_cbc_encrypt}, @code{des_ecb2_encrypt},
@code{des_ecb3_encrypt}, @code{des_ecb_encrypt},
@code{des_ede2_cbc_encrypt}, @code{des_ede3_cbc_encrypt},
@code{des_is_weak_key}, @code{des_key_sched}, @code{des_ncbc_encrypt}
@code{des_set_key}, and @code{des_set_odd_parity}.


Niels Möller's avatar
Niels Möller committed
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
@node Installation, Index, Reference, Top
@comment  node-name,  next,  previous,  up
@chapter Installation

Nettle uses @command{autoconf} and @command{automake}. To build it,
unpack the source and run

@example
./configure
make
make check
make install
@end example

1021
@noindent
Niels Möller's avatar
Niels Möller committed
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
to install in the default location, @file{/usr/local}. The library is
installed in @file{/use/local/lib/libnettle.a} and the include files are
installed in @file{/use/local/include/nettle/}.

Only static libraries are installed.

@node Index,  , Installation, Top
@comment  node-name,  next,  previous,  up
@unnumbered Function and Concept Index

@printindex cp

@bye