« back to all changes in this revision
Viewing changes to nettle.info
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Marek Habersack
- Date: 2004-05-04 15:56:02 UTC
- Revision ID: james.westby@ubuntu.com-20040504155602-7jbhw5mabvwksl3j
Tags: upstream-1.10
Import upstream version 1.10
- files added:
- examples
- sparc
- testsuite
- tools
- x86
added
removed
nettle.info
1
This is nettle.info, produced by makeinfo version 4.6 from
2
nettle.texinfo.
3
4
INFO-DIR-SECTION GNU Libraries
5
START-INFO-DIR-ENTRY
6
* Nettle: (nettle). A low-level cryptographics library.
7
END-INFO-DIR-ENTRY
8
9
Draft manual for the Nettle library. This manual corresponds to
10
version 1.5.
11
12
Copyright 2001 Niels M�ller
13
14
Permission is granted to make and distribute verbatim copies of this
15
manual provided the copyright notice and this permission notice are
16
preserved on all copies.
17
18
Permission is granted to copy and distribute modified versions of
19
this manual under the conditions for verbatim copying, provided also
20
that the sections entitled "Copying" and "GNU General Public License"
21
are included exactly as in the original, and provided that the entire
22
resulting derived work is distributed under the terms of a permission
23
notice identical to this one.
24
25
Permission is granted to copy and distribute translations of this
26
manual into another language, under the above conditions for modified
27
versions, except that this permission notice may be stated in a
28
translation approved by the Free Software Foundation.
29
30
31
File: nettle.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
32
33
Nettle
34
******
35
36
This document describes the nettle low-level cryptographic library. You
37
can use the library directly from your C programs, or (recommended)
38
write or use an object-oriented wrapper for your favorite language or
39
application.
40
41
This manual corresponds to version 1.5 of the library.
42
43
* Menu:
44
45
* Introduction:: What is Nettle?
46
* Copyright:: Your rights.
47
* Conventions::
48
* Example::
49
* Reference:: All Nettle functions and features.
50
* Nettle soup:: For the serious nettle hacker.
51
* Installation:: How to install Nettle.
52
* Index::
53
54
55
File: nettle.info, Node: Introduction, Next: Copyright, Prev: Top, Up: Top
56
57
Introduction
58
************
59
60
Nettle is a cryptographic library that is designed to fit easily in more
61
or less any context: In crypto toolkits for object-oriented languages
62
(C++, Python, Pike, ...), in applications like LSH or GNUPG, or even in
63
kernel space. In most contexts, you need more than the basic
64
cryptographic algorithms, you also need some way to keep track of
65
available algorithms, their properties and variants. You often have
66
some algorithm selection process, often dictated by a protocol you want
67
to implement.
68
69
And as the requirements of applications differ in subtle and not so
70
subtle ways, an API that fits one application well can be a pain to use
71
in a different context. And that is why there are so many different
72
cryptographic libraries around.
73
74
Nettle tries to avoid this problem by doing one thing, the low-level
75
crypto stuff, and providing a _simple_ but general interface to it. In
76
particular, Nettle doesn't do algorithm selection. It doesn't do memory
77
allocation. It doesn't do any I/O.
78
79
The idea is that one can build several application and context
80
specific interfaces on top of Nettle, and share the code, test cases,
81
benchmarks, documentation, etc. For this first version, the only
82
application using Nettle is LSH, and it uses an object-oriented
83
abstraction on top of the library.
84
85
This manual explains how to use the Nettle library. It also tries to
86
provide some background on the cryptography, and advice on how to best
87
put it to use.
88
89
90
File: nettle.info, Node: Copyright, Next: Conventions, Prev: Introduction, Up: Top
91
92
Copyright
93
*********
94
95
Nettle is distributed under the GNU General Public License (GPL) (see
96
the file COPYING for details). However, most of the individual files
97
are dual licensed under less restrictive licenses like the GNU Lesser
98
General Public License (LGPL), or are in the public domain. This means
99
that if you don't use the parts of nettle that are GPL-only, you have
100
the option to use the Nettle library just as if it were licensed under
101
the LGPL. To find the current status of particular files, you have to
102
read the copyright notices at the top of the files.
103
104
A list of the supported algorithms, their origins and licenses:
105
106
_AES_
107
The implementation of the AES cipher (also known as rijndael) is
108
written by Rafael Sevilla. Released under the LGPL.
109
110
_ARCFOUR_
111
The implementation of the ARCFOUR (also known as RC4) cipher is
112
written by Niels M�ller. Released under the LGPL.
113
114
_BLOWFISH_
115
The implementation of the BLOWFISH cipher is written by Werner
116
Koch, copyright owned by the Free Software Foundation. Also hacked
117
by Ray Dassen and Niels M�ller. Released under the GPL.
118
119
_CAST128_
120
The implementation of the CAST128 cipher is written by Steve Reid.
121
Released into the public domain.
122
123
_DES_
124
The implementation of the DES cipher is written by Dana L. How, and
125
released under the LGPL.
126
127
_MD2_
128
The implementation of MD2 is written by Andrew Kuchling, and hacked
129
some by Andreas Sigfridsson and Niels M�ller. Python Cryptography
130
Toolkit license (essentially public domain).
131
132
_MD4_
133
This is almost the same code as for MD5 below, with modifications
134
by Marcus Comstedt. Released into the public domain.
135
136
_MD5_
137
The implementation of the MD5 message digest is written by Colin
138
Plumb. It has been hacked some more by Andrew Kuchling and Niels
139
M�ller. Released into the public domain.
140
141
_SERPENT_
142
The implementation of the SERPENT cipher is written by Ross
143
Anderson, Eli Biham, and Lars Knudsen, adapted to LSH by Rafael
144
Sevilla, and to Nettle by Niels M�ller. Released under the GPL.
145
146
_SHA1_
147
The implementation of the SHA1 message digest is written by Peter
148
Gutmann, and hacked some more by Andrew Kuchling and Niels M�ller.
149
Released into the public domain.
150
151
_TWOFISH_
152
The implementation of the TWOFISH cipher is written by Ruud de
153
Rooij. Released under the LGPL.
154
155
156
File: nettle.info, Node: Conventions, Next: Example, Prev: Copyright, Up: Top
157
158
Conventions
159
***********
160
161
For each supported algorithm, there is an include file that defines a
162
_context struct_, a few constants, and declares functions for operating
163
on the context. The context struct encapsulates all information needed
164
by the algorithm, and it can be copied or moved in memory with no
165
unexpected effects.
166
167
For consistency, functions for different algorithms are very similar,
168
but there are some differences, for instance reflecting if the key setup
169
or encryption function differ for encryption and encryption, and whether
170
or not key setup can fail. There are also differences between algorithms
171
that don't show in function prototypes, but which the application must
172
nevertheless be aware of. There is no big difference between the
173
functions for stream ciphers and for block ciphers, although they should
174
be used quite differently by the application.
175
176
If your application uses more than one algorithm, you should probably
177
create an interface that is tailor-made for your needs, and then write a
178
few lines of glue code on top of Nettle.
179
180
By convention, for an algorithm named `foo', the struct tag for the
181
context struct is `foo_ctx', constants and functions uses prefixes like
182
`FOO_BLOCK_SIZE' (a constant) and `foo_set_key' (a function).
183
184
In all functions, strings are represented with an explicit length, of
185
type `unsigned', and a pointer of type `uint8_t *' or `const uint8_t
186
*'. For functions that transform one string to another, the argument
187
order is length, destination pointer and source pointer. Source and
188
destination areas are of the same length. Source and destination may be
189
the same, so that you can process strings in place, but they _must not_
190
overlap in any other way.
191
192
193
File: nettle.info, Node: Example, Next: Reference, Prev: Conventions, Up: Top
194
195
Example
196
*******
197
198
A simple example program that reads a file from standard in and writes
199
its SHA1 checksum on standard output should give the flavor of Nettle.
200
201
#include <stdio.h>
202
#include <stdlib.h>
203
204
#include <nettle/sha.h>
205
206
#define BUF_SIZE 1000
207
208
static void
209
display_hex(unsigned length, uint8_t *data)
210
{
211
unsigned i;
212
213
for (i = 0; i<length; i++)
214
printf("%2x ", data[i]);
215
216
printf("\n");
217
}
218
219
int
220
main(int argc, char **argv)
221
{
222
struct sha1_ctx ctx;
223
uint8_t buffer[BUF_SIZE];
224
uint8_t digest[SHA1_DIGEST_SIZE];
225
226
sha1_init(&ctx);
227
for (;;)
228
{
229
int done = fread(buffer, 1, sizeof(buffer), stdin);
230
sha1_update(&ctx, done, buffer);
231
if (done < sizeof(buffer))
232
break;
233
}
234
if (ferror(stdin))
235
return EXIT_FAILURE;
236
237
sha1_digest(&ctx, SHA1_DIGEST_SIZE, digest);
238
239
display_hex(SHA1_DIGEST_SIZE, digest);
240
return EXIT_SUCCESS;
241
}
242
243
244
File: nettle.info, Node: Reference, Next: Nettle soup, Prev: Example, Up: Top
245
246
Reference
247
*********
248
249
This chapter describes all the Nettle functions, grouped by family.
250
251
* Menu:
252
253
* Hash functions::
254
* Cipher functions::
255
* Cipher Block Chaining::
256
* Keyed hash functions::
257
* Public-key algorithms::
258
* Randomness::
259
* Miscellaneous functions::
260
* Compatibility functions::
261
262
263
File: nettle.info, Node: Hash functions, Next: Cipher functions, Prev: Reference, Up: Reference
264
265
Hash functions
266
==============
267
268
A cryptographic "hash function" is a function that takes variable size
269
strings, and maps them to strings of fixed, short, length. There are
270
naturally lots of collisions, as there are more possible 1MB files than
271
20 byte strings. But the function is constructed such that is hard to
272
find the collisions. More precisely, a cryptographic hash function `H'
273
should have the following properties:
274
275
_One-way_
276
Given a hash value `H(x)' it is hard to find a string `x' that
277
hashes to that value.
278
279
_Collision-resistant_
280
It is hard to find two different strings, `x' and `y', such that
281
`H(x)' = `H(y)'.
282
283
284
Hash functions are useful as building blocks for digital signatures,
285
message authentication codes, pseudo random generators, association of
286
unique id:s to documents, and many other things.
287
288
There are several fairly popular hash functions. Collisions have been
289
found the the compression function of MD4, and in variants of MD5.
290
These functions are therefore not recommended for new applications.
291
The recommended hash function for new applications is SHA1.
292
293
MD5
294
---
295
296
MD5 is a message digest function constructed by Ronald Rivest, and
297
described in `RFC 1321'. It outputs message digests of 128 bits, or 16
298
octets. Nettle defines MD5 in `<nettle/md5.h>'.
299
300
- Context struct: struct md5_ctx
301
302
- Constant: MD5_DIGEST_SIZE
303
The size of an MD5 digest, i.e. 16.
304
305
- Constant: MD5_DATA_SIZE
306
The internal block size of MD5. Useful for some special
307
constructions, in particular HMAC-MD5.
308
309
- Function: void md5_init (struct md5_ctx *CTX)
310
Initialize the MD5 state.
311
312
- Function: void md5_update (struct md5_ctx *CTX, unsigned LENGTH,
313
const uint8_t *DATA)
314
Hash some more data.
315
316
- Function: void md5_digest (struct md5_ctx *CTX, unsigned LENGTH,
317
uint8_t *DIGEST)
318
Performs final processing and extracts the message digest, writing
319
it to DIGEST. LENGTH may be smaller than `MD5_DIGEST_SIZE', in
320
which case only the first LENGTH octets of the digest are written.
321
322
This function also resets the context in the same way as
323
`md5_init'.
324
325
The normal way to use MD5 is to call the functions in order: First
326
`md5_init', then `md5_update' zero or more times, and finally
327
`md5_digest'. After `md5_digest', the context is reset to its initial
328
state, so you can start over calling `md5_update' to hash new data.
329
330
To start over, you can call `md5_init' at any time.
331
332
MD2
333
---
334
335
MD2 is another hash function of Ronald Rivests', described in `RFC
336
1319'. It outputs message digests of 128 bits, or 16 octets. Nettle
337
defines MD2 in `<nettle/md2.h>'.
338
339
- Context struct: struct md2_ctx
340
341
- Constant: MD2_DIGEST_SIZE
342
The size of an MD2 digest, i.e. 16.
343
344
- Constant: MD2_DATA_SIZE
345
The internal block size of MD2.
346
347
- Function: void md2_init (struct md2_ctx *CTX)
348
Initialize the MD2 state.
349
350
- Function: void md2_update (struct md2_ctx *CTX, unsigned LENGTH,
351
const uint8_t *DATA)
352
Hash some more data.
353
354
- Function: void md2_digest (struct md2_ctx *CTX, unsigned LENGTH,
355
uint8_t *DIGEST)
356
Performs final processing and extracts the message digest, writing
357
it to DIGEST. LENGTH may be smaller than `MD2_DIGEST_SIZE', in
358
which case only the first LENGTH octets of the digest are written.
359
360
This function also resets the context in the same way as
361
`md2_init'.
362
363
MD4
364
---
365
366
MD4 is a predecessor of MD5, described in `RFC 1320'. Like MD5, it is
367
constructed by Ronald Rivest. It outputs message digests of 128 bits,
368
or 16 octets. Nettle defines MD4 in `<nettle/md4.h>'. Because of
369
discovered weaknesses, use of MD4 is not recommended, but it is
370
sometimes needed for compatibility with existing applications and
371
protocols.
372
373
- Context struct: struct md4_ctx
374
375
- Constant: MD4_DIGEST_SIZE
376
The size of an MD4 digest, i.e. 16.
377
378
- Constant: MD4_DATA_SIZE
379
The internal block size of MD4.
380
381
- Function: void md4_init (struct md4_ctx *CTX)
382
Initialize the MD4 state.
383
384
- Function: void md4_update (struct md4_ctx *CTX, unsigned LENGTH,
385
const uint8_t *DATA)
386
Hash some more data.
387
388
- Function: void md4_digest (struct md4_ctx *CTX, unsigned LENGTH,
389
uint8_t *DIGEST)
390
Performs final processing and extracts the message digest, writing
391
it to DIGEST. LENGTH may be smaller than `MD4_DIGEST_SIZE', in
392
which case only the first LENGTH octets of the digest are written.
393
394
This function also resets the context in the same way as
395
`md4_init'.
396
397
SHA1
398
----
399
400
SHA1 is a hash function specified by "NIST" (The U.S. National Institute
401
for Standards and Technology). It outputs hash values of 160 bits, or 20
402
octets. Nettle defines SHA1 in `<nettle/sha.h>'.
403
404
The functions are analogous to the MD5 ones.
405
406
- Context struct: struct sha1_ctx
407
408
- Constant: SHA1_DIGEST_SIZE
409
The size of an SHA1 digest, i.e. 20.
410
411
- Constant: SHA1_DATA_SIZE
412
The internal block size of SHA1. Useful for some special
413
constructions, in particular HMAC-SHA1.
414
415
- Function: void sha1_init (struct sha1_ctx *CTX)
416
Initialize the SHA1 state.
417
418
- Function: void sha1_update (struct sha1_ctx *CTX, unsigned LENGTH,
419
const uint8_t *DATA)
420
Hash some more data.
421
422
- Function: void sha1_digest (struct sha1_ctx *CTX, unsigned LENGTH,
423
uint8_t *DIGEST)
424
Performs final processing and extracts the message digest, writing
425
it to DIGEST. LENGTH may be smaller than `SHA1_DIGEST_SIZE', in
426
which case only the first LENGTH octets of the digest are written.
427
428
This function also resets the context in the same way as
429
`sha1_init'.
430
431
SHA256
432
------
433
434
SHA256 is another hash function specified by "NIST", intended as a
435
replacement for SHA1, generating larger digests. It outputs hash values
436
of 256 bits, or 32 octets. Nettle defines SHA256 in `<nettle/sha.h>'.
437
438
The functions are analogous to the MD5 ones.
439
440
- Context struct: struct sha256_ctx
441
442
- Constant: SHA256_DIGEST_SIZE
443
The size of an SHA256 digest, i.e. 20.
444
445
- Constant: SHA256_DATA_SIZE
446
The internal block size of SHA256. Useful for some special
447
constructions, in particular HMAC-SHA256.
448
449
- Function: void sha256_init (struct sha256_ctx *CTX)
450
Initialize the SHA256 state.
451
452
- Function: void sha256_update (struct sha256_ctx *CTX, unsigned
453
LENGTH, const uint8_t *DATA)
454
Hash some more data.
455
456
- Function: void sha256_digest (struct sha256_ctx *CTX, unsigned
457
LENGTH, uint8_t *DIGEST)
458
Performs final processing and extracts the message digest, writing
459
it to DIGEST. LENGTH may be smaller than `SHA256_DIGEST_SIZE', in
460
which case only the first LENGTH octets of the digest are written.
461
462
This function also resets the context in the same way as
463
`sha256_init'.
464
465
`struct nettle_hash'
466
--------------------
467
468
Nettle includes a struct including information about the supported hash
469
functions. It is defined in `<nettle/nettle-meta.h>', and is used by
470
Nettle's implementation of HMAC *note Keyed hash functions::.
471
472
- Meta struct: `struct nettle_hash' name context_size digest_size
473
block_size init update digest
474
The last three attributes are function pointers, of types
475
`nettle_hash_init_func', `nettle_hash_update_func', and
476
`nettle_hash_digest_func'. The first argument to these functions is
477
`void *' pointer so a context struct, which is of size
478
`context_size'.
479
480
- Constant Struct: struct nettle_cipher nettle_md5
481
- Constant Struct: struct nettle_cipher nettle_sha1
482
- Constant Struct: struct nettle_cipher nettle_sha256
483
These are all the hash functions that Nettle implements.
484
485
486
File: nettle.info, Node: Cipher functions, Next: Cipher Block Chaining, Prev: Hash functions, Up: Reference
487
488
Cipher functions
489
================
490
491
A "cipher" is a function that takes a message or "plaintext" and a
492
secret "key" and transforms it to a "ciphertext". Given only the
493
ciphertext, but not the key, it should be hard to find the plaintext.
494
Given matching pairs of plaintext and ciphertext, it should be hard to
495
find the key.
496
497
There are two main classes of ciphers: Block ciphers and stream
498
ciphers.
499
500
A block cipher can process data only in fixed size chunks, called
501
"blocks". Typical block sizes are 8 or 16 octets. To encrypt arbitrary
502
messages, you usually have to pad it to an integral number of blocks,
503
split it into blocks, and then process each block. The simplest way is
504
to process one block at a time, independent of each other. That mode of
505
operation is called "ECB", Electronic Code Book mode. However, using
506
ECB is usually a bad idea. For a start, plaintext blocks that are equal
507
are transformed to ciphertext blocks that are equal; that leaks
508
information about the plaintext. Usually you should apply the cipher is
509
some feedback mode, "CBC" (Cipher Block Chaining) being one of the most
510
popular. *Note Cipher Block Chaining::, for information on how to apply
511
CBC with Nettle.
512
513
A stream cipher can be used for messages of arbitrary length; a
514
typical stream cipher is a keyed pseudo-random generator. To encrypt a
515
plaintext message of N octets, you key the generator, generate N octets
516
of pseudo-random data, and XOR it with the plaintext. To decrypt,
517
regenerate the same stream using the key, XOR it to the ciphertext, and
518
the plaintext is recovered.
519
520
*Caution:* The first rule for this kind of cipher is the same as for
521
a One Time Pad: _never_ ever use the same key twice.
522
523
A common misconception is that encryption, by itself, implies
524
authentication. Say that you and a friend share a secret key, and you
525
receive an encrypted message. You apply the key, and get a plaintext
526
message that makes sense to you. Can you then be sure that it really was
527
your friend that wrote the message you're reading? The answer is no. For
528
example, if you were using a block cipher in ECB mode, an attacker may
529
pick up the message on its way, and reorder, delete or repeat some of
530
the blocks. Even if the attacker can't decrypt the message, he can
531
change it so that you are not reading the same message as your friend
532
wrote. If you are using a block cipher in CBC mode rather than ECB, or
533
are using a stream cipher, the possibilities for this sort of attack
534
are different, but the attacker can still make predictable changes to
535
the message.
536
537
It is recommended to _always_ use an authentication mechanism in
538
addition to encrypting the messages. Popular choices are Message
539
Authentication Codes like HMAC-SHA1 *note Keyed hash functions::, or
540
digital signatures like RSA.
541
542
Some ciphers have so called "weak keys", keys that results in
543
undesirable structure after the key setup processing, and should be
544
avoided. In Nettle, the presence of weak keys for a cipher mean that the
545
key setup function can fail, so you have to check its return value. In
546
addition, the context struct has a field `status', that is set to a
547
non-zero value if key setup fails. When possible, avoid algorithm that
548
have weak keys. There are several good ciphers that don't have any weak
549
keys.
550
551
To encrypt a message, you first initialize a cipher context for
552
encryption or decryption with a particular key. You then use the context
553
to process plaintext or ciphertext messages. The initialization is known
554
as called "key setup". With Nettle, it is recommended to use each
555
context struct for only one direction, even if some of the ciphers use a
556
single key setup function that can be used for both encryption and
557
decryption.
558
559
AES
560
---
561
562
AES is a quite new block cipher, specified by NIST as a replacement for
563
the older DES standard. The standard is the result of a competition
564
between cipher designers. The winning design, also known as RIJNDAEL,
565
was constructed by Joan Daemen and Vincent Rijnmen.
566
567
Like all the AES candidates, the winning design uses a block size of
568
128 bits, or 16 octets, and variable key-size, 128, 192 and 256 bits
569
(16, 24 and 32 octets) being the allowed key sizes. It does not have
570
any weak keys. Nettle defines AES in `<nettle/aes.h>'.
571
572
- Context struct: struct aes_ctx
573
574
- Constant: AES_BLOCK_SIZE
575
The AES block-size, 16
576
577
- Constant: AES_MIN_KEY_SIZE
578
579
- Constant: AES_MAX_KEY_SIZE
580
581
- Constant: AES_KEY_SIZE
582
Default AES key size, 32
583
584
- Function: void aes_set_key (struct aes_ctx *CTX, unsigned LENGTH,
585
const uint8_t *KEY)
586
Initialize the cipher. The same function is used for both
587
encryption and decryption.
588
589
- Function: void aes_encrypt (struct aes_ctx *CTX, unsigned LENGTH,
590
const uint8_t *DST, uint8_t *SRC)
591
Encryption function. LENGTH must be an integral multiple of the
592
block size. If it is more than one block, the data is processed in
593
ECB mode. `src' and `dst' may be equal, but they must not overlap
594
in any other way.
595
596
- Function: void aes_decrypt (struct aes_ctx *CTX, unsigned LENGTH,
597
const uint8_t *DST, uint8_t *SRC)
598
Analogous to `aes_encrypt'
599
600
ARCFOUR
601
-------
602
603
ARCFOUR is a stream cipher, also known under the trade marked name RC4,
604
and it is one of the fastest ciphers around. A problem is that the key
605
setup of ARCFOUR is quite weak, you should never use keys with
606
structure, keys that are ordinary passwords, or sequences of keys like
607
"secret:1", "secret:2", ..... If you have keys that don't look like
608
random bit strings, and you want to use ARCFOUR, always hash the key
609
before feeding it to ARCFOUR. For example
610
611
/* A more robust key setup function for ARCFOUR */
612
void
613
arcfour_set_key_hashed(struct arcfour_ctx *ctx,
614
unsigned length, const uint8_t *key)
615
{
616
struct sha1_ctx hash;
617
uint8_t digest[SHA1_DIGEST_SIZE];
618
619
sha1_init(&hash);
620
sha1_update(&hash, length, key);
621
sha1_digest(&hash, SHA1_DIGEST_SIZE, digest);
622
623
arcfour_set_key(ctx, SHA1_DIGEST_SIZE, digest);
624
}
625
626
Nettle defines ARCFOUR in `<nettle/arcfour.h>'.
627
628
- Context struct: struct arcfour_ctx
629
630
- Constant: ARCFOUR_MIN_KEY_SIZE
631
Minimum key size, 1
632
633
- Constant: ARCFOUR_MAX_KEY_SIZE
634
Maximum key size, 256
635
636
- Constant: ARCFOUR_KEY_SIZE
637
Default ARCFOUR key size, 16
638
639
- Function: void arcfour_set_key (struct arcfour_ctx *CTX, unsigned
640
LENGTH, const uint8_t *KEY)
641
Initialize the cipher. The same function is used for both
642
encryption and decryption.
643
644
- Function: void arcfour_crypt (struct arcfour_ctx *CTX, unsigned
645
LENGTH, const uint8_t *KEY)
646
Encrypt some data. The same function is used for both encryption
647
and decryption. Unlike the block ciphers, this function modifies
648
the context, so you can split the data into arbitrary chunks and
649
encrypt them one after another. The result is the same as if you
650
had called `arcfour_crypt' only once with all the data.
651
652
CAST128
653
-------
654
655
CAST-128 is a block cipher, specified in `RFC 2144'. It uses a 64 bit
656
(8 octets) block size, and a variable key size of up to 128 bits.
657
Nettle defines cast128 in `<nettle/cast128.h>'.
658
659
- Context struct: struct cast128_ctx
660
661
- Constant: CAST128_BLOCK_SIZE
662
The CAST128 block-size, 8
663
664
- Constant: CAST128_MIN_KEY_SIZE
665
Minimum CAST128 key size, 5
666
667
- Constant: CAST128_MAX_KEY_SIZE
668
Maximum CAST128 key size, 16
669
670
- Constant: CAST128_KEY_SIZE
671
Default CAST128 key size, 16
672
673
- Function: void cast128_set_key (struct cast128_ctx *CTX, unsigned
674
LENGTH, const uint8_t *KEY)
675
Initialize the cipher. The same function is used for both
676
encryption and decryption.
677
678
- Function: void cast128_encrypt (struct cast128_ctx *CTX, unsigned
679
LENGTH, const uint8_t *DST, uint8_t *SRC)
680
Encryption function. LENGTH must be an integral multiple of the
681
block size. If it is more than one block, the data is processed in
682
ECB mode. `src' and `dst' may be equal, but they must not overlap
683
in any other way.
684
685
- Function: void cast128_decrypt (struct cast128_ctx *CTX, unsigned
686
LENGTH, const uint8_t *DST, uint8_t *SRC)
687
Analogous to `cast128_encrypt'
688
689
BLOWFISH
690
--------
691
692
BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block
693
size of 64 bits (8 octets), and a variable key size, up to 448 bits. It
694
has some weak keys. Nettle defines BLOWFISH in `<nettle/blowfish.h>'.
695
696
- Context struct: struct blowfish_ctx
697
698
- Constant: BLOWFISH_BLOCK_SIZE
699
The BLOWFISH block-size, 8
700
701
- Constant: BLOWFISH_MIN_KEY_SIZE
702
Minimum BLOWFISH key size, 8
703
704
- Constant: BLOWFISH_MAX_KEY_SIZE
705
Maximum BLOWFISH key size, 56
706
707
- Constant: BLOWFISH_KEY_SIZE
708
Default BLOWFISH key size, 16
709
710
- Function: int blowfish_set_key (struct blowfish_ctx *CTX, unsigned
711
LENGTH, const uint8_t *KEY)
712
Initialize the cipher. The same function is used for both
713
encryption and decryption. Returns 1 on success, and 0 if the key
714
was weak. Calling `blowfish_encrypt' or `blowfish_decrypt' with a
715
weak key will crash with an assert violation.
716
717
- Function: void blowfish_encrypt (struct blowfish_ctx *CTX, unsigned
718
LENGTH, const uint8_t *DST, uint8_t *SRC)
719
Encryption function. LENGTH must be an integral multiple of the
720
block size. If it is more than one block, the data is processed in
721
ECB mode. `src' and `dst' may be equal, but they must not overlap
722
in any other way.
723
724
- Function: void blowfish_decrypt (struct blowfish_ctx *CTX, unsigned
725
LENGTH, const uint8_t *DST, uint8_t *SRC)
726
Analogous to `blowfish_encrypt'
727
728
DES
729
---
730
731
DES is the old Data Encryption Standard, specified by NIST. It uses a
732
block size of 64 bits (8 octets), and a key size of 56 bits. However,
733
the key bits are distributed over 8 octets, where the least significant
734
bit of each octet is used for parity. A common way to use DES is to
735
generate 8 random octets in some way, then set the least significant bit
736
of each octet to get odd parity, and initialize DES with the resulting
737
key.
738
739
The key size of DES is so small that keys can be found by brute
740
force, using specialized hardware or lots of ordinary work stations in
741
parallel. One shouldn't be using plain DES at all today, if one uses
742
DES at all one should be using DES3 or "triple DES", see below.
743
744
DES also has some weak keys. Nettle defines DES in `<nettle/des.h>'.
745
746
- Context struct: struct des_ctx
747
748
- Constant: DES_BLOCK_SIZE
749
The DES block-size, 8
750
751
- Constant: DES_KEY_SIZE
752
DES key size, 8
753
754
- Function: int des_set_key (struct des_ctx *CTX, const uint8_t *KEY)
755
Initialize the cipher. The same function is used for both
756
encryption and decryption. Returns 1 on success, and 0 if the key
757
was weak or had bad parity. Calling `des_encrypt' or `des_decrypt'
758
with a bad key will crash with an assert violation.
759
760
- Function: void des_encrypt (struct des_ctx *CTX, unsigned LENGTH,
761
const uint8_t *DST, uint8_t *SRC)
762
Encryption function. LENGTH must be an integral multiple of the
763
block size. If it is more than one block, the data is processed in
764
ECB mode. `src' and `dst' may be equal, but they must not overlap
765
in any other way.
766
767
- Function: void des_decrypt (struct des_ctx *CTX, unsigned LENGTH,
768
const uint8_t *DST, uint8_t *SRC)
769
Analogous to `des_encrypt'
770
771
- Function: void des_fix_parity (unsigned LENGTH, uint8_t *DST, const
772
uint8_t *SRC)
773
Adjusts the parity bits to match DES's requirements. You need this
774
function if you have created a random-looking string by a key
775
agreement protocol, and want to use it as a DES key. DST and SRC
776
may be equal.
777
778
DES3
779
----
780
781
The inadequate key size of DES has already been mentioned. One way to
782
increase the key size is to pipe together several DES boxes with
783
independent keys. It turns out that using two DES ciphers is not as
784
secure as one might think, even if the key size of the combination is a
785
respectable 112 bits.
786
787
The standard way to increase DES's key size is to use three DES
788
boxes. The mode of operation is a little peculiar: the middle DES box
789
is wired in the reverse direction. To encrypt a block with DES3, you
790
encrypt it using the first 56 bits of the key, then _decrypt_ it using
791
the middle 56 bits of the key, and finally encrypt it again using the
792
last 56 bits of the key. This is known as "ede" triple-DES, for
793
"encrypt-decrypt-encrypt".
794
795
The "ede" construction provides some backward compatibility, as you
796
get plain single DES simply by feeding the same key to all three boxes.
797
That should help keeping down the gate count, and the price, of hardware
798
circuits implementing both plain DES and DES3.
799
800
DES3 has a key size of 168 bits, but just like plain DES, useless
801
parity bits are inserted, so that keys are represented as 24 octets
802
(192 bits). As a 112 bit key is large enough to make brute force
803
attacks impractical, some applications uses a "two-key" variant of
804
triple-DES. In this mode, the same key bits are used for the first and
805
the last DES box in the pipe, while the middle box is keyed
806
independently. The two-key variant is believed to be secure, i.e. there
807
are no known attacks significantly better than brute force.
808
809
Naturally, it's simple to implement triple-DES on top of Nettle's DES
810
functions. Nettle includes an implementation of three-key "ede"
811
triple-DES, it is defined in the same place as plain DES,
812
`<nettle/des.h>'.
813
814
- Context struct: struct des3_ctx
815
816
- Constant: DES3_BLOCK_SIZE
817
The DES3 block-size is the same as DES_BLOCK_SIZE, 8
818
819
- Constant: DES3_KEY_SIZE
820
DES key size, 24
821
822
- Function: int des3_set_key (struct des3_ctx *CTX, const uint8_t *KEY)
823
Initialize the cipher. The same function is used for both
824
encryption and decryption. Returns 1 on success, and 0 if the key
825
was weak or had bad parity. Calling `des_encrypt' or `des_decrypt'
826
with a bad key will crash with an assert violation.
827
828
For random-looking strings, you can use `des_fix_parity' to adjust
829
the parity bits before calling `des3_set_key'.
830
831
- Function: void des3_encrypt (struct des3_ctx *CTX, unsigned LENGTH,
832
const uint8_t *DST, uint8_t *SRC)
833
Encryption function. LENGTH must be an integral multiple of the
834
block size. If it is more than one block, the data is processed in
835
ECB mode. `src' and `dst' may be equal, but they must not overlap
836
in any other way.
837
838
- Function: void des3_decrypt (struct des3_ctx *CTX, unsigned LENGTH,
839
const uint8_t *DST, uint8_t *SRC)
840
Analogous to `des_encrypt'
841
842
SERPENT
843
-------
844
845
SERPENT is one of the AES finalists, designed by Ross Anderson, Eli
846
Biham and Lars Knudsen. Thus, the interface and properties are similar
847
to AES'. One peculiarity is that it is quite pointless to use it with
848
anything but the maximum key size, smaller keys are just padded to
849
larger ones. Nettle defines SERPENT in `<nettle/serpent.h>'.
850
851
- Context struct: struct serpent_ctx
852
853
- Constant: SERPENT_BLOCK_SIZE
854
The SERPENT block-size, 16
855
856
- Constant: SERPENT_MIN_KEY_SIZE
857
Minimum SERPENT key size, 16
858
859
- Constant: SERPENT_MAX_KEY_SIZE
860
Maximum SERPENT key size, 32
861
862
- Constant: SERPENT_KEY_SIZE
863
Default SERPENT key size, 32
864
865
- Function: void serpent_set_key (struct serpent_ctx *CTX, unsigned
866
LENGTH, const uint8_t *KEY)
867
Initialize the cipher. The same function is used for both
868
encryption and decryption.
869
870
- Function: void serpent_encrypt (struct serpent_ctx *CTX, unsigned
871
LENGTH, const uint8_t *DST, uint8_t *SRC)
872
Encryption function. LENGTH must be an integral multiple of the
873
block size. If it is more than one block, the data is processed in
874
ECB mode. `src' and `dst' may be equal, but they must not overlap
875
in any other way.
876
877
- Function: void serpent_decrypt (struct serpent_ctx *CTX, unsigned
878
LENGTH, const uint8_t *DST, uint8_t *SRC)
879
Analogous to `serpent_encrypt'
880
881
TWOFISH
882
-------
883
884
Another AES finalist, this one designed by Bruce Schneier and others.
885
Nettle defines it in `<nettle/twofish.h>'.
886
887
- Context struct: struct twofish_ctx
888
889
- Constant: TWOFISH_BLOCK_SIZE
890
The TWOFISH block-size, 16
891
892
- Constant: TWOFISH_MIN_KEY_SIZE
893
Minimum TWOFISH key size, 16
894
895
- Constant: TWOFISH_MAX_KEY_SIZE
896
Maximum TWOFISH key size, 32
897
898
- Constant: TWOFISH_KEY_SIZE
899
Default TWOFISH key size, 32
900
901
- Function: void twofish_set_key (struct twofish_ctx *CTX, unsigned
902
LENGTH, const uint8_t *KEY)
903
Initialize the cipher. The same function is used for both
904
encryption and decryption.
905
906
- Function: void twofish_encrypt (struct twofish_ctx *CTX, unsigned
907
LENGTH, const uint8_t *DST, uint8_t *SRC)
908
Encryption function. LENGTH must be an integral multiple of the
909
block size. If it is more than one block, the data is processed in
910
ECB mode. `src' and `dst' may be equal, but they must not overlap
911
in any other way.
912
913
- Function: void twofish_decrypt (struct twofish_ctx *CTX, unsigned
914
LENGTH, const uint8_t *DST, uint8_t *SRC)
915
Analogous to `twofish_encrypt'
916
917
`struct nettle_cipher'
918
----------------------
919
920
Nettle includes a struct including information about some of the more
921
regular cipher functions. It should be considered a little experimental,
922
but can be useful for applications that need a simple way to handle
923
various algorithms. Nettle defines these structs in
924
`<nettle/nettle-meta.h>'.
925
926
- Meta struct: `struct nettle_cipher' name context_size block_size
927
key_size set_encrypt_key set_decrypt_key encrypt decrypt
928
The last four attributes are function pointers, of types
929
`nettle_set_key_func' and `nettle_crypt_func'. The first argument
930
to these functions is a `void *' pointer to a context struct,
931
which is of size `context_size'.
932
933
- Constant Struct: struct nettle_cipher nettle_aes128
934
- Constant Struct: struct nettle_cipher nettle_aes192
935
- Constant Struct: struct nettle_cipher nettle_aes256
936
- Constant Struct: struct nettle_cipher nettle_arcfour128
937
- Constant Struct: struct nettle_cipher nettle_cast128
938
- Constant Struct: struct nettle_cipher nettle_serpent128
939
- Constant Struct: struct nettle_cipher nettle_serpent192
940
- Constant Struct: struct nettle_cipher nettle_serpent256
941
- Constant Struct: struct nettle_cipher nettle_twofish128
942
- Constant Struct: struct nettle_cipher nettle_twofish192
943
- Constant Struct: struct nettle_cipher nettle_twofish256
944
Nettle includes such structs for all the _regular_ ciphers, i.e.
945
ones without weak keys or other oddity.
946
947
948
File: nettle.info, Node: Cipher Block Chaining, Next: Keyed hash functions, Prev: Cipher functions, Up: Reference
949
950
Cipher Block Chaining
951
=====================
952
953
When using CBC mode, plaintext blocks are not encrypted independently
954
of each other, like in Electronic Cook Book mode. Instead, when
955
encrypting a block in CBC mode, the previous ciphertext block is XOR:ed
956
with the plaintext before it is fed to the block cipher. When
957
encrypting the first block, a random block called an "IV", or
958
Initialization Vector, is used as the "previous ciphertext block". The
959
IV should be chosen randomly, but it need not be kept secret, and can
960
even be transmitted in the clear together with the encrypted data.
961
962
In symbols, if `E_k' is the encryption function of a block cipher,
963
and `IV' is the initialization vector, then `n' plaintext blocks
964
`M_1',... `M_n' are transformed into `n' ciphertext blocks `C_1',...
965
`C_n' as follows:
966
967
C_1 = E_k(IV XOR M_1)
968
C_2 = E_k(C_1 XOR M_2)
969
970
...
971
972
C_n = E_k(C_(n-1) XOR M_n)
973
974
Nettle includes a few utility functions for applying a block cipher
975
in Cipher Block Chaining (CBC) mode. The functions uses `void *' to
976
pass cipher contexts around.
977
978
- Function: void cbc_encrypt (void *CTX, void (*F)(), unsigned
979
BLOCK_SIZE, uint8_t *IV, unsigned LENGTH, uint8_t *DST, const
980
uint8_t *SRC)
981
- Function: void cbc_decrypt (void *CTX, void (*F)(), unsigned
982
BLOCK_SIZE, uint8_t *IV, unsigned LENGTH, uint8_t *DST, const
983
uint8_t *SRC)
984
Applies the encryption or decryption function F in CBC mode. The
985
function F is really typed as
986
987
`void f (void *CTX, unsigned LENGTH, uint8_t DST, const uint8_t
988
*SRC)',
989
990
and the `cbc_encrypt' and `cbc_decrypt' functions pass their
991
argument CTX on to F.
992
993
There are also some macros to help use these functions correctly.
994
995
- Macro: CBC_CTX (CONTEXT_TYPE, BLOCK_SIZE)
996
Expands into
997
{
998
context_type ctx;
999
uint8_t iv[block_size];
1000
}
1001
1002
It can be used to define a CBC context struct, either directly,
1003
1004
struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;
1005
1006
or to give it a struct tag,
1007
1008
struct aes_cbc_ctx CBC_CTX (struct aes_ctx, AES_BLOCK_SIZE);
1009
1010
- Macro: CBC_SET_IV (CTX, IV)
1011
First argument is a pointer to a context struct as defined by
1012
`CBC_CTX', and the second is a pointer to an Initialization Vector
1013
(IV) that is copied into that context.
1014
1015
- Macro: CBC_ENCRYPT (CTX, F, LENGTH, DST, SRC)
1016
- Macro: CBC_DECRYPT (CTX, F, LENGTH, DST, SRC)
1017
A simpler way to invoke `cbc_encrypt' and `cbc_decrypt'. The first
1018
argument is a pointer to a context struct as defined by `CBC_CTX',
1019
and the second argument is an encryption or decryption function
1020
following Nettle's conventions. The last three arguments define
1021
the source and destination area for the operation.
1022
1023
These macros use some tricks to make the compiler display a warning
1024
if the types of F and CTX don't match, e.g. if you try to use an
1025
`struct aes_ctx' context with the `des_encrypt' function.
1026
1027
1028
File: nettle.info, Node: Keyed hash functions, Next: Public-key algorithms, Prev: Cipher Block Chaining, Up: Reference
1029
1030
Keyed Hash Functions
1031
====================
1032
1033
A "keyed hash function", or "Message Authentication Code" (MAC) is a
1034
function that takes a key and a message, and produces fixed size MAC.
1035
It should be hard to compute a message and a matching MAC without
1036
knowledge of the key. It should also be hard to compute the key given
1037
only messages and corresponding MACs.
1038
1039
Keyed hash functions are useful primarily for message authentication,
1040
when the Alice and Bob shares a secret: The sender, Alice, computes the
1041
MAC and attaches it to the message. The receiver, Bob, also computes
1042
the MAC of the message, using the same key, and compares that to
1043
Alice's value. If they match, Bob can be assured that the message has
1044
not been modified on it's way from Alice.
1045
1046
However, unlike digital signatures, this assurance is not
1047
transferable. Bob can't show the message and the MAC to a third party
1048
and prove that Alice sent that message. Not even if he gives away the
1049
key to the third party. The reason is that the _same_ key is used on
1050
both sides, and anyone knowing the key can create a correct MAC for any
1051
message. If Bob believes that only he and Alice knows the key, and he
1052
knows that he didn't attach a MAC to a particular message, he knows it
1053
must be Alice who did it. However, the third party can't distinguish
1054
between MAC created by Alice and one created by Bob.
1055
1056
Keyed hash functions are typically a lot faster than digital
1057
signatures as well.
1058
1059
HMAC
1060
----
1061
1062
One can build keyed hash functions from ordinary hash functions. Older
1063
constructions simply concatenate secret key and message and hashes
1064
that, but such constructions have weaknesses. A better construction is
1065
HMAC, described in `RFC 2104'.
1066
1067
For an underlying hash function `H', with digest size `l' and
1068
internal block size `b', HMAC-H is constructed as follows: From a given
1069
key `k', two distinct subkeys `k_i' and `k_o' are constructed, both of
1070
length `b'. The HMAC-H of a message `m' is then computed as `H(k_o |
1071
H(k_i | m))', where `|' denotes string concatenation.
1072
1073
HMAC keys can be of any length, but it is recommended to use keys of
1074
length `l', the digest size of the underlying hash function `H'. Keys
1075
that are longer than `b' are shortened to length `l' by hashing with
1076
`H', so arbitrarily long keys aren't very useful.
1077
1078
Nettle's HMAC functions are defined in `<nettle/hmac.h>'. There are
1079
abstract functions that use a pointer to a `struct nettle_hash' to
1080
represent the underlying hash function and `void *' pointers that point
1081
to three different context structs for that hash function. There are
1082
also concrete functions for HMAC-MD5, HMAC-SHA1, and HMAC-SHA256.
1083
First, the abstract functions:
1084
1085
- Function: void hmac_set_key (void *OUTER, void *INNER, void *STATE,
1086
const struct nettle_hash *H, unsigned LENGTH, const uint8_t
1087
*KEY)
1088
Initializes the three context structs from the key. The OUTER and
1089
INNER contexts corresponds to the subkeys `k_o' and `k_i'. STATE
1090
is used for hashing the message, and is initialized as a copy of
1091
the INNER context.
1092
1093
- Function: void hmac_update (void *STATE, const struct nettle_hash
1094
*H, unsigned LENGTH, const uint8_t *DATA)
1095
This function is called zero or more times to process the message.
1096
Actually, `hmac_update(state, H, length, data)' is equivalent to
1097
`H->update(state, length, data)', so if you wish you can use the
1098
ordinary update function of the underlying hash function instead.
1099
1100
- Function: void hmac_digest (const void *OUTER, const void *INNER,
1101
void *STATE, const struct nettle_hash *H, unsigned LENGTH,
1102
uint8_t *DIGEST)
1103
Extracts the MAC of the message, writing it to DIGEST. OUTER and
1104
INNER are not modified. LENGTH is usually equal to
1105
`H->digest_size', but if you provide a smaller value, only the
1106
first LENGTH octets of the MAC are written.
1107
1108
This function also resets the STATE context so that you can start
1109
over processing a new message (with the same key).
1110
1111
Like for CBC, there are some macros to help use these functions
1112
correctly.
1113
1114
- Macro: HMAC_CTX (TYPE)
1115
Expands into
1116
{
1117
type outer;
1118
type inner;
1119
type state;
1120
}
1121
1122
It can be used to define a HMAC context struct, either directly,
1123
1124
struct HMAC_CTX(struct md5_ctx) ctx;
1125
1126
or to give it a struct tag,
1127
1128
struct hmac_md5_ctx HMAC_CTX (struct md5_ctx);
1129
1130
- Macro: HMAC_SET_KEY (CTX, H, LENGTH, KEY)
1131
CTX is a pointer to a context struct as defined by `HMAC_CTX', H
1132
is a pointer to a `const struct nettle_hash' describing the
1133
underlying hash function (so it must match the type of the
1134
components of CTX). The last two arguments specify the secret key.
1135
1136
- Macro: HMAC_DIGEST (CTX, H, LENGTH, DIGEST)
1137
CTX is a pointer to a context struct as defined by `HMAC_CTX', H
1138
is a pointer to a `const struct nettle_hash' describing the
1139
underlying hash function. The last two arguments specify where the
1140
digest is written.
1141
1142
Note that there is no `HMAC_UPDATE' macro; simply call `hmac_update'
1143
function directly, or the update function of the underlying hash
1144
function.
1145
1146
Concrete HMAC functions
1147
-----------------------
1148
1149
Now we come to the specialized HMAC functions, which are easier to use
1150
than the general HMAC functions.
1151
1152
HMAC-MD5
1153
........
1154
1155
- Context struct: struct hmac_md5_ctx
1156
1157
- Function: void hmac_md5_set_key (struct hmac_md5_ctx *CTX, unsigned
1158
KEY_LENGTH, const uint8_t *KEY)
1159
Initializes the context with the key.
1160
1161
- Function: void hmac_md5_update (struct hmac_md5_ctx *CTX, unsigned
1162
LENGTH, const uint8_t *DATA)
1163
Process some more data.
1164
1165
- Function: void hmac_md5_digest (struct hmac_md5_ctx *CTX, unsigned
1166
LENGTH, uint8_t *DIGEST)
1167
Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
1168
`MD5_DIGEST_SIZE', in which case only the first LENGTH octets of
1169
the MAC are written.
1170
1171
This function also resets the context for processing new messages,
1172
with the same key.
1173
1174
HMAC-SHA1
1175
.........
1176
1177
- Context struct: struct hmac_sha1_ctx
1178
1179
- Function: void hmac_sha1_set_key (struct hmac_sha1_ctx *CTX,
1180
unsigned KEY_LENGTH, const uint8_t *KEY)
1181
Initializes the context with the key.
1182
1183
- Function: void hmac_sha1_update (struct hmac_sha1_ctx *CTX, unsigned
1184
LENGTH, const uint8_t *DATA)
1185
Process some more data.
1186
1187
- Function: void hmac_sha1_digest (struct hmac_sha1_ctx *CTX, unsigned
1188
LENGTH, uint8_t *DIGEST)
1189
Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
1190
`SHA1_DIGEST_SIZE', in which case only the first LENGTH octets of
1191
the MAC are written.
1192
1193
This function also resets the context for processing new messages,
1194
with the same key.
1195
1196
HMAC-SHA256
1197
...........
1198
1199
- Context struct: struct hmac_sha256_ctx
1200
1201
- Function: void hmac_sha256_set_key (struct hmac_sha256_ctx *CTX,
1202
unsigned KEY_LENGTH, const uint8_t *KEY)
1203
Initializes the context with the key.
1204
1205
- Function: void hmac_sha256_update (struct hmac_sha256_ctx *CTX,
1206
unsigned LENGTH, const uint8_t *DATA)
1207
Process some more data.
1208
1209
- Function: void hmac_sha256_digest (struct hmac_sha256_ctx *CTX,
1210
unsigned LENGTH, uint8_t *DIGEST)
1211
Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
1212
`SHA256_DIGEST_SIZE', in which case only the first LENGTH octets
1213
of the MAC are written.
1214
1215
This function also resets the context for processing new messages,
1216
with the same key.
1217
1218
1219
File: nettle.info, Node: Public-key algorithms, Next: Randomness, Prev: Keyed hash functions, Up: Reference
1220
1221
Public-key algorithms
1222
=====================
1223
1224
Nettle uses GMP, the GNU bignum library, for all calculations with
1225
large numbers. In order to use the public-key features of Nettle, you
1226
must install GMP, at least version 3.0, before compiling Nettle, and
1227
you need to link your programs with `-lgmp'.
1228
1229
The concept of "Public-key" encryption and digital signatures was
1230
discovered by Whitfield Diffie and Martin E. Hellman and described in a
1231
paper 1976. In traditional, "symmetric", cryptography, sender and
1232
receiver share the same keys, and these keys must be distributed in a
1233
secure way. And if there are many users or entities that need to
1234
communicate, each _pair_ needs a shared secret key known by nobody else.
1235
1236
Public-key cryptography uses trapdoor one-way functions. A "one-way
1237
function" is a function `F' such that it is easy to compute the value
1238
`F(x)' for any `x', but given a value `y', it is hard to compute a
1239
corresponding `x' such that `y = F(x)'. Two examples are cryptographic
1240
hash functions, and exponentiation in certain groups.
1241
1242
A "trapdoor one-way function" is a function `F' that is one-way,
1243
unless one knows some secret information about `F'. If one knows the
1244
secret, it is easy to compute both `F' and it's inverse. If this
1245
sounds strange, look at the RSA example below.
1246
1247
Two important uses for one-way functions with trapdoors are
1248
public-key encryption, and digital signatures. Of these, I won't say
1249
more about public-key encryption, as that isn't yet supported by
1250
Nettle. So the rest of this chapter is about digital signatures.
1251
1252
To use a digital signature algorithm, one must first create a
1253
"key-pair": A public key and a corresponding private key. The private
1254
key is used to sign messages, while the public key is used for verifying
1255
that that signatures and messages match. Some care must be taken when
1256
distributing the public key; it need not be kept secret, but if a bad
1257
guy is able to replace it (in transit, or in some user's list of known
1258
public keys), bad things may happen.
1259
1260
There are two operations one can do with the keys. The signature
1261
operation takes a message and a private key, and creates a signature for
1262
the message. A signature is some string of bits, usually at most a few
1263
thousand bits or a few hundred octets. Unlike paper-and-ink signatures,
1264
the digital signature depends on the message, so one can't cut it out of
1265
context and glue it to a different message.
1266
1267
The verification operation takes a public key, a message, and a
1268
string that is claimed to be a signature on the message, and returns
1269
true or false. If it returns true, that means that the three input
1270
values matched, and the verifier can be sure that someone went through
1271
with the signature operation on that very message, and that the
1272
"someone" also knows the private key corresponding to the public key.
1273
1274
The desired properties of a digital signature algorithm are as
1275
follows: Given the public key and pairs of messages and valid
1276
signatures on them, it should be hard to compute the private key, and
1277
it should also be hard to create a new message and signature that is
1278
accepted by the verification operation.
1279
1280
Besides signing meaningful messages, digital signatures can be used
1281
for authorization. A server can be configured with a public key, such
1282
that any client that connects to the service is given a random nonce
1283
message. If the server gets a reply with a correct signature matching
1284
the nonce message and the configured public key, the client is granted
1285
access. So the configuration of the server can be understood as "grant
1286
access to whoever knows the private key corresponding to this
1287
particular public key, and to no others".
1288
1289
* Menu:
1290
1291
* RSA:: The RSA public key algorithm.
1292
* DSA:: The DSA digital signature algorithm.
1293
1294
1295
File: nettle.info, Node: RSA, Next: DSA, Prev: Public-key algorithms, Up: Public-key algorithms
1296
1297
RSA
1298
---
1299
1300
The RSA algorithm was the first practical digital signature algorithm
1301
that was constructed. It was described 1978 in a paper by Ronald
1302
Rivest, Adi Shamir and L.M. Adleman, and the technique was also
1303
patented in 1983. The patent expired on September 20, 2000, and since
1304
that day, RSA can be used freely.
1305
1306
It's remarkably simple to describe the trapdoor function behind RSA.
1307
The "one-way"-function used is
1308
1309
F(x) = x^e mod n
1310
1311
I.e. raise x to the `e':th power, while discarding all multiples of
1312
`n'. The pair of numbers `n' and `e' is the public key. `e' can be
1313
quite small, even `e = 3' has been used, although slightly larger
1314
numbers are recommended. `n' should be about 1000 bits or larger.
1315
1316
If `n' is large enough, and properly chosen, the inverse of F, the
1317
computation of `e':th roots modulo `n', is very difficult. But,
1318
where's the trapdoor?
1319
1320
Let's first look at how RSA key-pairs are generated. First `n' is
1321
chosen as the product of two large prime numbers `p' and `q' of roughly
1322
the same size (so if `n' is 1000 bits, `p' and `q' are about 500 bits
1323
each). One also computes the number `phi = (p-1)(q-1)', in mathematical
1324
speak, phi is the order of the multiplicative group of integers modulo
1325
n.
1326
1327
Next, `e' is chosen. It must have no factors in common with phi (in
1328
particular, it must be odd), but can otherwise be chosen more or less
1329
randomly. `e = 65537' is a popular choice, because it makes raising to
1330
the `e':th power particularly efficient, and being prime, it usually
1331
has no factors common with `phi'.
1332
1333
Finally, a number `d', `d < n' is computed such that `e d mod phi =
1334
1'. It can be shown that such a number exists (this is why `e' and
1335
`phi' must have no common factors), and that for all x,
1336
1337
(x^e)^d mod n = x^(ed) mod n = (x^d)^e mod n = x
1338
1339
Using Euclid's algorithm, `d' can be computed quite easily from
1340
`phi' and `e'. But it is still hard to get `d' without knowing `phi',
1341
which depends on the factorization of `n'.
1342
1343
So `d' is the trapdoor, if we know `d' and `y = F(x)', we can
1344
recover x as `y^d mod n'. `d' is also the private half of the RSA
1345
key-pair.
1346
1347
The most common signature operation for RSA is defined in `PKCS#1',
1348
a specification by RSA Laboratories. The message to be signed is first
1349
hashed using a cryptographic hash function, e.g. MD5 or SHA1. Next,
1350
some padding, the ASN.1 "Algorithm Identifier" for the hash function,
1351
and the message digest itself, are concatenated and converted to a
1352
number `x'. The signature is computed from `x' and the private key as
1353
`s = x^d mod n'(1). The signature, `s' is a number of about the same
1354
size of `n', and it usually encoded as a sequence of octets, most
1355
significant octet first.
1356
1357
The verification operation is straight-forward, `x' is computed from
1358
the message in the same way as above. Then `s^e mod n' is computed, the
1359
operation returns true if and only if the result equals `x'.
1360
1361
Nettle's RSA support
1362
--------------------
1363
1364
Nettle represents RSA keys using two structures that contain large
1365
numbers (of type `mpz_t').
1366
1367
- Context struct: rsa_public_key size n e
1368
`size' is the size, in octets, of the modulo, and is used
1369
internally. `n' and `e' is the public key.
1370
1371
- Context struct: rsa_private_key size d p q a b c
1372
`size' is the size, in octets, of the modulo, and is used
1373
internally. `d' is the secret exponent, but it is not actually
1374
used when signing. Instead, the factors `p' and `q', and the
1375
parameters `a', `b' and `c' are used. They are computed from `p',
1376
`q' and `d' such that `a e mod (p - 1) = 1, b e mod (q - 1) = 1, c
1377
q mod p= 1'.
1378
1379
Before use, these structs must be initialized by calling one of
1380
1381
- Function: void rsa_public_key_init (struct rsa_public_key *PUB)
1382
- Function: void rsa_private_key_init (struct rsa_private_key *KEY)
1383
Calls `mpz_init' on all numbers in the key struct.
1384
1385
and when finished with them, the space for the numbers must be
1386
deallocated by calling one of
1387
1388
- Function: void rsa_public_key_clear (struct rsa_public_key *PUB)
1389
- Function: void rsa_private_key_clear (struct rsa_private_key *KEY)
1390
Calls `mpz_clear' on all numbers in the key struct.
1391
1392
In general, Nettle's RSA functions deviates from Nettle's "no memory
1393
allocation"-policy. Space for all the numbers, both in the key structs
1394
above, and temporaries, are allocated dynamically. For information on
1395
how to customize allocation, see *Note GMP Allocation: (gmp)Custom
1396
Allocation.
1397
1398
When you have assigned values to the attributes of a key, you must
1399
call
1400
1401
- Function: int rsa_public_key_prepare (struct rsa_public_key *PUB)
1402
- Function: int rsa_private_key_prepare (struct rsa_private_key *KEY)
1403
Computes the octet size of the key (stored in the `size' attribute,
1404
and may also do other basic sanity checks. Returns one if
1405
successful, or zero if the key can't be used, for instance if the
1406
modulo is smaller than the minimum size specified by PKCS#1.
1407
1408
Before signing or verifying a message, you first hash it with the
1409
appropriate hash function. You pass the hash function's context struct
1410
to the RSA signature function, and it will extract the message digest
1411
and do the rest of the work. There are also alternative functions that
1412
take the MD5 or SHA1 hash digest as argument.
1413
1414
Creation and verification of signatures is done with the following
1415
functions:
1416
1417
- Function: void rsa_md5_sign (const struct rsa_private_key *KEY,
1418
struct md5_ctx *HASH, mpz_t SIGNATURE)
1419
- Function: void rsa_sha1_sign (const struct rsa_private_key *KEY,
1420
struct sha1_ctx *HASH, mpz_t SIGNATURE)
1421
The signature is stored in SIGNATURE (which must have been
1422
`mpz_init':ed earlier). The hash context is reset so that it can be
1423
used for new messages.
1424
1425
- Function: void rsa_md5_sign_digest (const struct rsa_private_key
1426
*KEY, const uint8_t *DIGEST, mpz_t SIGNATURE)
1427
- Function: void rsa_sha1_sign_digest (const struct rsa_private_key
1428
*KEY, const uint8_t *DIGEST, mpz_t SIGNATURE);
1429
Creates a signature from the given hash digest. DIGEST should
1430
point to a digest of size `MD5_DIGEST_SIZE' or `SHA1_DIGEST_SIZE',
1431
respectively. The signature is stored in SIGNATURE (which must
1432
have been `mpz_init':ed earlier)
1433
1434
- Function: int rsa_md5_verify (const struct rsa_public_key *KEY,
1435
struct md5_ctx *HASH, const mpz_t SIGNATURE)
1436
- Function: int rsa_sha1_verify (const struct rsa_public_key *KEY,
1437
struct sha1_ctx *HASH, const mpz_t SIGNATURE)
1438
Returns 1 if the signature is valid, or 0 if it isn't. In either
1439
case, the hash context is reset so that it can be used for new
1440
messages.
1441
1442
- Function: int rsa_md5_verify_digest (const struct rsa_public_key
1443
*KEY, const uint8_t *DIGEST, const mpz_t SIGNATURE)
1444
- Function: int rsa_sha1_verify_digest (const struct rsa_public_key
1445
*KEY, const uint8_t *DIGEST, const mpz_t SIGNATURE)
1446
Returns 1 if the signature is valid, or 0 if it isn't. DIGEST
1447
should point to a digest of size `MD5_DIGEST_SIZE' or
1448
`SHA1_DIGEST_SIZE', respectively.
1449
1450
If you need to use the RSA trapdoor, the private key, in a way that
1451
isn't supported by the above functions Nettle also includes a function
1452
that computes `x^d mod n' and nothing more, using the CRT optimization.
1453
1454
- Function: void rsa_compute_root (struct rsa_private_key *KEY, mpz_t
1455
X, const mpz_t M)
1456
Computes `x = m^d', efficiently.
1457
1458
At last, how do you create new keys?
1459
1460
- Function: int rsa_generate_keypair (struct rsa_public_key *PUB,
1461
struct rsa_private_key *KEY, void *RANDOM_CTX,
1462
nettle_random_func RANDOM, void *PROGRESS_CTX,
1463
nettle_progress_func PROGRESS, unsigned N_SIZE, unsigned
1464
E_SIZE);
1465
There are lots of parameters. PUB and KEY is where the resulting
1466
key pair is stored. The structs should be initialized, but you
1467
don't need to call `rsa_public_key_prepare' or
1468
`rsa_private_key_prepare' after key generation.
1469
1470
RANDOM_CTX and RANDOM is a randomness generator.
1471
`random(random_ctx, length, dst)' should generate `length' random
1472
octets and store them at `dst'. For advice, see *Note Randomness::.
1473
1474
PROGRESS and PROGRESS_CTX can be used to get callbacks during the
1475
key generation process, in order to uphold an illusion of
1476
progress. PROGRESS can be NULL, in that case there are no
1477
callbacks.
1478
1479
SIZE_N is the desired size of the modulo, in bits. If SIZE_E is
1480
non-zero, it is the desired size of the public exponent and a
1481
random exponent of that size is selected. But if E_SIZE is zero,
1482
it is assumed that the caller has already chosen a value for `e',
1483
and stored it in PUB. Returns 1 on success, and 0 on failure. The
1484
function can fail for example if if N_SIZE is too small, or if
1485
E_SIZE is zero and `pub->e' is an even number.
1486
1487
---------- Footnotes ----------
1488
1489
(1) Actually, the computation is not done like this, it is done more
1490
efficiently using `p', `q' and the Chinese remainder theorem (CRT). But
1491
the result is the same.
1492
1493
1494
File: nettle.info, Node: DSA, Prev: RSA, Up: Public-key algorithms
1495
1496
Nettle's DSA support
1497
--------------------
1498
1499
The DSA digital signature algorithm is more complex than RSA. It was
1500
specified during the early 1990s, and in 1994 NIST published FIPS 186
1501
which is the authoritative specification. Sometimes DSA is referred to
1502
using the acronym DSS, for Digital Signature Standard.
1503
1504
For DSA, the underlying mathematical problem is the computation of
1505
discreet logarithms. The public key consists of a large prime `p', a
1506
small prime `q' which is a factor of `p-1', a number `g' which
1507
generates a subgroup of order `q' modulo `p', and an element `y' in
1508
that subgroup.
1509
1510
The size of `q' is fixed to 160 bits, to match with the SHA1 hash
1511
algorithm which is used in DSA. The size of `q' is in principle
1512
unlimited, but the standard specifies only nine specific sizes: `512 +
1513
l*64', where `l' is between 0 and 8. Thus, the maximum size of `p' is
1514
1024 bits, at that is also the recommended size.
1515
1516
The subgroup requirement means that if you compute
1517
1518
g^t mod p
1519
1520
for all possible integers `t', you will get precisely `q' distinct
1521
values.
1522
1523
The private key is a secret exponent `x', such that
1524
1525
g^x = y mod p
1526
1527
In mathematical speak, `x' is the "discrete logarithm" of `y' mod
1528
`p', with respect to the generator `d'. The size of `x' will also be
1529
about 160 bits.
1530
1531
The signature generation algorithm is randomized; in order to create
1532
a DSA signature, you need a good source for random numbers (*note
1533
Randomness::).
1534
1535
To create a signature, one starts with the hash digest of the
1536
message, `h', which is a 160 bit number, and a random number `k,
1537
0<k<q', also 160 bits. Next, one computes
1538
1539
r = (g^k mod p) mod q
1540
s = k^-1 (h + x r) mod q
1541
1542
The signature is the pair `(r, s)', two 160 bit numbers. Note the
1543
two different mod operations when computing `r', and the use of the
1544
secret exponent `x'.
1545
1546
To verify a signature, one first checks that `0 < r,s < q', and then
1547
one computes backwards,
1548
1549
w = s^-1 mod q
1550
v = (g^(w h) y^(w r) mod p) mod q
1551
1552
The signature is valid if `v = r'. This works out because `w = s^-1
1553
mod q = k (h + x r)^-1 mod q', so that
1554
1555
g^(w h) y^(w r) = g^(w h) (g^x)^(w r) = g^(w (h + x r)) = g^k
1556
1557
When reducing mod `q' this yields `r'. Note that when verifying a
1558
signature, we don't know either `k' or `x': those numbers are secret.
1559
1560
If you can choose between RSA and DSA, which one is best? Both are
1561
believed to be secure. DSA gained popularity in the late 1990s, as a
1562
patent free alternative to RSA. Now that the RSA patents have expired,
1563
there's no compelling reason to want to use DSA.
1564
1565
DSA signatures are smaller than RSA signatures, which is important
1566
for some specialized applications.
1567
1568
From a practical point of view, DSA's need for a good randomness
1569
source is a serious disadvantage. If you ever use the same `k' (and
1570
`r') for two different message, you leak your private key.
1571
1572
Nettle's DSA support
1573
--------------------
1574
1575
Like for RSA, Nettle represents DSA keys using two structures,
1576
containing values of type `mpz_t'. For information on how to customize
1577
allocation, see *Note GMP Allocation: (gmp)Custom Allocation.
1578
1579
Most of the DSA functions are very similar to the corresponding RSA
1580
functions, but there are a few differences pointed out below. For a
1581
start, there are no functions corresponding to `rsa_public_key_prepare'
1582
and `rsa_private_key_prepare'.
1583
1584
- Context struct: dsa_public_key p q g y
1585
The public parameters described above.
1586
1587
- Context struct: dsa_private_key x
1588
The private key `x'.
1589
1590
Before use, these structs must be initialized by calling one of
1591
1592
- Function: void dsa_public_key_init (struct dsa_public_key *PUB)
1593
- Function: void dsa_private_key_init (struct dsa_private_key *KEY)
1594
Calls `mpz_init' on all numbers in the key struct.
1595
1596
When finished with them, the space for the numbers must be
1597
deallocated by calling one of
1598
1599
- Function: void dsa_public_key_clear (struct dsa_public_key *PUB)
1600
- Function: void dsa_private_key_clear (struct dsa_private_key *KEY)
1601
Calls `mpz_clear' on all numbers in the key struct.
1602
1603
Signatures are represented using the structure below, and need to be
1604
initialized and cleared in the same way as the key structs.
1605
1606
- Context struct: dsa_signature r s
1607
1608
- Function: void dsa_signature_init (struct dsa_signature *SIGNATURE)
1609
- Function: void dsa_signature_clear (struct dsa_signature *SIGNATURE)
1610
You must call `dsa_signature_init' before creating or using a
1611
signature, and call `dsa_signature_clear' when you are finished
1612
with it.
1613
1614
For signing, you need to provide both the public and the private key
1615
(unlike RSA, where the private key struct includes all information
1616
needed for signing), and a source for random numbers. Signatures
1617
always use the SHA1 hash function.
1618
1619
- Function: void dsa_sign (const struct dsa_public_key *PUB, const
1620
struct dsa_private_key *KEY, void *RANDOM_CTX,
1621
nettle_random_func RANDOM, struct sha1_ctx *HASH, struct
1622
dsa_signature *SIGNATURE)
1623
- Function: void dsa_sign_digest (const struct dsa_public_key *PUB,
1624
const struct dsa_private_key *KEY, void *RANDOM_CTX,
1625
nettle_random_func RANDOM, const uint8_t *DIGEST, struct
1626
dsa_signature *SIGNATURE)
1627
Creates a signature from the given hash context or digest.
1628
RANDOM_CTX and RANDOM is a randomness generator.
1629
`random(random_ctx, length, dst)' should generate `length' random
1630
octets and store them at `dst'. For advice, see *Note Randomness::.
1631
1632
Verifying signatures is a little easier, since no randomness
1633
generator is needed. The functions are
1634
1635
- Function: int dsa_verify (const struct dsa_public_key *KEY, struct
1636
sha1_ctx *HASH, const struct dsa_signature *SIGNATURE)
1637
- Function: int dsa_verify_digest (const struct dsa_public_key *KEY,
1638
const uint8_t *DIGEST, const struct dsa_signature *SIGNATURE)
1639
Verifies a signature. Returns 1 if the signature is valid,
1640
otherwise 0.
1641
1642
Key generation uses mostly the same parameters as the corresponding
1643
RSA function.
1644
1645
- Function: int dsa_generate_keypair (struct dsa_public_key *PUB,
1646
struct dsa_private_key *KEY, void *RANDOM_CTX,
1647
nettle_random_func RANDOM, void *PROGRESS_CTX,
1648
nettle_progress_func PROGRESS, unsigned BITS)
1649
PUB and KEY is where the resulting key pair is stored. The structs
1650
should be initialized before you call this function.
1651
1652
RANDOM_CTX and RANDOM is a randomness generator.
1653
`random(random_ctx, length, dst)' should generate `length' random
1654
octets and store them at `dst'. For advice, see *Note Randomness::.
1655
1656
PROGRESS and PROGRESS_CTX can be used to get callbacks during the
1657
key generation process, in order to uphold an illusion of
1658
progress. PROGRESS can be NULL, in that case there are no
1659
callbacks.
1660
1661
BITS is the desired size of `p', in bits. To generate keys that
1662
conform to the standard, you must use a value of the form `512 +
1663
l*64', for `0 <= l <= 8'. Keys smaller than 768 bits are not
1664
considered secure, so you should probably stick to 1024.
1665
Non-standard sizes are possible, in particular sizes larger than
1666
1024 bits, although DSA implementations can not in general be
1667
expected to support such keys. Also note that using very large
1668
keys doesn't make much sense, because the security is also limited
1669
by the size of the smaller prime `q', which is always 160 bits.
1670
1671
Returns 1 on success, and 0 on failure. The function will fail if
1672
BITS is too small.
1673
1674
1675
File: nettle.info, Node: Randomness, Next: Miscellaneous functions, Prev: Public-key algorithms, Up: Reference
1676
1677
Randomness
1678
==========
1679
1680
A crucial ingredient in many cryptographic contexts is randomness: Let
1681
`p' be a random prime, choose a random initialization vector `iv', a
1682
random key `k' and a random exponent `e', etc. In the theories, it is
1683
assumed that you have plenty of randomness around. If this assumption
1684
is not true in practice, systems that are otherwise perfectly secure,
1685
can be broken. Randomness has often turned out to be the weakest link
1686
in the chain.
1687
1688
In non-cryptographic applications, such as games as well as
1689
scientific simulation, a good randomness generator usually means a
1690
generator that has good statistical properties, and is seeded by some
1691
simple function of things like the current time, process id, and host
1692
name.
1693
1694
However, such a generator is inadequate for cryptography, for at
1695
least two reasons:
1696
1697
* It's too easy for an attacker to guess the initial seed. Even if
1698
it will take some 2^32 tries before he guesses right, that's far
1699
too easy. For example, if the process id is 16 bits, the
1700
resolution of "current time" is one second, and the attacker knows
1701
what day the generator was seeded, there are only about 2^32
1702
possibilities to try if all possible values for the process id and
1703
time-of-day are tried.
1704
1705
* The generator output reveals too much. By observing only a small
1706
segment of the generator's output, its internal state can be
1707
recovered, and from there, all previous output and all future
1708
output can be computed by the attacker.
1709
1710
A randomness generator that is used for cryptographic purposes must
1711
have better properties. Let's first look at the seeding, as the issues
1712
here are mostly independent of the rest of the generator. The initial
1713
state of the generator (its seed) must be unguessable by the attacker.
1714
So what's unguessable? It depends on what the attacker already knows.
1715
The concept used in information theory to reason about such things is
1716
called "entropy", or "conditional entropy" (not to be confused with the
1717
thermodynamic concept with the same name). A reasonable requirement is
1718
that the seed contains a conditional entropy of at least some 80-100
1719
bits. This property can be explained as follows: Allow the attacker to
1720
ask `n' yes-no-questions, of his own choice, about the seed. If the
1721
attacker, using this question-and-answer session, as well as any other
1722
information he knows about the seeding process, still can't guess the
1723
seed correctly, then the conditional entropy is more than `n' bits.
1724
1725
Let's look at an example. Say information about timing of received
1726
network packets is used in the seeding process. If there is some random
1727
network traffic going on, this will contribute some bits of entropy or
1728
"unguessability" to the seed. However, if the attacker can listen in to
1729
the local network, or if all but a small number of the packets were
1730
transmitted by machines that the attacker can monitor, this additional
1731
information makes the seed easier for the attacker to figure out. Even
1732
if the information is exactly the same, the conditional entropy, or
1733
unguessability, is smaller for an attacker that knows some of it already
1734
before the hypothetical question-and-answer session.
1735
1736
Seeding of good generators is usually based on several sources. The
1737
key point here is that the amount of unguessability that each source
1738
contributes, depends on who the attacker is. Some sources that have been
1739
used are:
1740
1741
High resolution timing of i/o activities
1742
Such as completed blocks from spinning hard disks, network
1743
packets, etc. Getting access to such information is quite system
1744
dependent, and not all systems include suitable hardware. If
1745
available, it's one of the better randomness source one can find
1746
in a digital, mostly predictable, computer.
1747
1748
User activity
1749
Timing and contents of user interaction events is another popular
1750
source that is available for interactive programs (even if I
1751
suspect that it is sometimes used in order to make the user feel
1752
good, not because the quality of the input is needed or used
1753
properly). Obviously, not available when a machine is unattended.
1754
Also beware of networks: User interaction that happens across a
1755
long serial cable, TELNET session, or even SSH session may be
1756
visible to an attacker, in full or partially.
1757
1758
Audio input
1759
Any room, or even a microphone input that's left unconnected, is a
1760
source of some random background noise, which can be fed into the
1761
seeding process.
1762
1763
Specialized hardware
1764
Hardware devices with the sole purpose of generating random data
1765
have been designed. They range from radioactive samples with an
1766
attached Geiger counter, to amplification of the inherent noise in
1767
electronic components such as diodes and resistors, to
1768
low-frequency sampling of chaotic systems. Hashing successive
1769
images of a Lava lamp is a spectacular example of the latter type.
1770
1771
Secret information
1772
Secret information, such as user passwords or keys, or private
1773
files stored on disk, can provide some unguessability. A problem
1774
is that if the information is revealed at a later time, the
1775
unguessability vanishes. Another problem is that this kind of
1776
information tends to be fairly constant, so if you rely on it and
1777
seed your generator regularly, you risk constructing almost
1778
similar seeds or even constructing the same seed more than once.
1779
1780
For all practical sources, it's difficult but important to provide a
1781
reliable lower bound on the amount of unguessability that it provides.
1782
Two important points are to make sure that the attacker can't observe
1783
your sources (so if you like the Lava lamp idea, remember that you have
1784
to get your own lamp, and not put it by a window or anywhere else where
1785
strangers can see it), and that hardware failures are detected. What if
1786
the bulb in the Lava lamp, which you keep locked into a cupboard
1787
following the above advice, breaks after a few months?
1788
1789
So let's assume that we have been able to find an unguessable seed,
1790
which contains at least 80 bits of conditional entropy, relative to all
1791
attackers that we care about (typically, we must at the very least
1792
assume that no attacker has root privileges on our machine).
1793
1794
How do we generate output from this seed, and how much can we get?
1795
Some generators (notably the Linux `/dev/random' generator) tries to
1796
estimate available entropy and restrict the amount of output. The goal
1797
is that if you read 128 bits from `/dev/random', you should get 128
1798
"truly random" bits. This is a property that is useful in some
1799
specialized circumstances, for instance when generating key material for
1800
a one time pad, or when working with unconditional blinding, but in most
1801
cases, it doesn't matter much. For most application, there's no limit on
1802
the amount of useful "random" data that we can generate from a small
1803
seed; what matters is that the seed is unguessable and that the
1804
generator has good cryptographic properties.
1805
1806
At the heart of all generators lies its internal state. Future output
1807
is determined by the internal state alone. Let's call it the generator's
1808
key. The key is initialized from the unguessable seed. Important
1809
properties of a generator are:
1810
1811
"Key-hiding"
1812
An attacker observing the output should not be able to recover the
1813
generator's key.
1814
1815
"Independence of outputs"
1816
Observing some of the output should not help the attacker to guess
1817
previous or future output.
1818
1819
"Forward secrecy"
1820
Even if an attacker compromises the generator's key, he should not
1821
be able to guess the generator output _before_ the key compromise.
1822
1823
"Recovery from key compromise"
1824
If an attacker compromises the generator's key, he can compute
1825
_all_ future output. This is inevitable if the generator is seeded
1826
only once, at startup. However, the generator can provide a
1827
reseeding mechanism, to achieve recovery from key compromise. More
1828
precisely: If the attacker compromises the key at a particular
1829
time `t_1', there is another later time `t_2', such that if the
1830
attacker observes all output generated between `t_1' and `t_2', he
1831
still can't guess what output is generated after `t_2'.
1832
1833
1834
Nettle includes one randomness generator that is believed to have all
1835
the above properties, and two simpler ones.
1836
1837
ARCFOUR, like any stream cipher, can be used as a randomness
1838
generator. Its output should be of reasonable quality, if the seed is
1839
hashed properly before it is used with `arcfour_set_key'. There's no
1840
single natural way to reseed it, but if you need reseeding, you should
1841
be using Yarrow instead.
1842
1843
The "lagged Fibonacci" generator in `<nettle/knuth-lfib.h>' is a
1844
fast generator with good statistical properties, but is *not* for
1845
cryptographic use, and therefore not documented here. It is included
1846
mostly because the Nettle test suite needs to generate some test data
1847
from a small seed.
1848
1849
The recommended generator to use is Yarrow, described below.
1850
1851
Yarrow
1852
------
1853
1854
Yarrow is a family of pseudo-randomness generators, designed for
1855
cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson.
1856
Yarrow-160 is described in a paper at
1857
<http://www.counterpane.com/yarrow.html>, and it uses SHA1 and
1858
triple-DES, and has a 160-bit internal state. Nettle implements
1859
Yarrow-256, which is similar, but uses SHA256 and AES to get an
1860
internal state of 256 bits.
1861
1862
Yarrow was an almost finished project, the paper mentioned above is
1863
the closest thing to a specification for it, but some smaller details
1864
are left out. There is no official reference implementation or test
1865
cases. This section includes an overview of Yarrow, but for the
1866
details of Yarrow-256, as implemented by Nettle, you have to consult
1867
the source code. Maybe a complete specification can be written later.
1868
1869
Yarrow can use many sources (at least two are needed for proper
1870
reseeding), and two randomness "pools", referred to as the "slow pool"
1871
and the "fast pool". Input from the sources is fed alternatingly into
1872
the two pools. When one of the sources has contributed 100 bits of
1873
entropy to the fast pool, a "fast reseed" happens and the fast pool is
1874
mixed into the internal state. When at least two of the sources have
1875
contributed at least 160 bits each to the slow pool, a "slow reseed"
1876
takes place. The contents of both pools are mixed into the internal
1877
state. These procedures should ensure that the generator will eventually
1878
recover after a key compromise.
1879
1880
The output is generated by using AES to encrypt a counter, using the
1881
generator's current key. After each request for output, another 256
1882
bits are generated which replace the key. This ensures forward secrecy.
1883
1884
Yarrow can also use a "seed file" to save state across restarts.
1885
Yarrow is seeded by either feeding it the contents of the previous seed
1886
file, or feeding it input from its sources until a slow reseed happens.
1887
1888
Nettle defines Yarrow-256 in `<nettle/yarrow.h>'.
1889
1890
- Context struct: struct yarrow256_ctx
1891
1892
- Context struct: struct yarrow_source
1893
Information about a single source.
1894
1895
- Constant: YARROW256_SEED_FILE_SIZE
1896
The size of the Yarrow-256 seed file.
1897
1898
- Function: void yarrow256_init (struct yarrow256_ctx *CTX, unsigned
1899
NSOURCES, struct yarrow_source *SOURCES)
1900
Initializes the yarrow context, and its NSOURCES sources. It's
1901
possible to use call it with NSOURCES=0 and SOURCES=NULL, if you
1902
don't need the update features.
1903
1904
- Function: void yarrow256_seed (struct yarrow256_ctx *CTX, unsigned
1905
LENGTH, uint8_t *SEED_FILE)
1906
Seeds Yarrow-256 from a previous seed file. LENGTH should be at
1907
least `YARROW256_SEED_FILE_SIZE', but it can be larger.
1908
1909
The generator will trust you that the SEED_FILE data really is
1910
unguessable. After calling this function, you _must_ overwrite the
1911
old seed file with the contents of `CTX->seed_file'. If it's
1912
possible for several processes to read the seed file at about the
1913
same time, access must be coordinated, for example using lock
1914
files.
1915
1916
- Function: int yarrow256_update (struct yarrow256_ctx *CTX, unsigned
1917
SOURCE, unsigned ENTROPY, unsigned LENGTH, const uint8_t
1918
*DATA)
1919
Updates the generator with data from source SOURCE (an index that
1920
must be smaller than the number of sources). ENTROPY is your
1921
estimated lower bound for the entropy in the data, measured in
1922
bits. Calling update with zero ENTROPY is always safe, no matter
1923
if the data is random or not.
1924
1925
Returns 1 if a reseed happened, in which case the seed file can be
1926
overwritten with the contents of `CTX->seed_file'. Otherwise, the
1927
function returns 0.
1928
1929
- Function: void yarrow256_random (struct yarrow256_ctx *CTX, unsigned
1930
LENGTH, uint8_t *DST)
1931
Generates LENGTH octets of output. The generator must be seeded
1932
before you call this function.
1933
1934
If you don't need forward secrecy, e.g. if you need non-secret
1935
randomness for initialization vectors or padding, you can gain some
1936
efficiency by buffering, calling this function for reasonably large
1937
blocks of data, say 100-1000 octets at a time.
1938
1939
- Function: int yarrow256_is_seeded (struct yarrow256_ctx *CTX)
1940
Returns 1 if the generator is seeded and ready to generate output,
1941
otherwise 0.
1942
1943
- Function: unsigned yarrow256_needed_sources (struct yarrow256_ctx
1944
*CTX)
1945
Returns the number of sources that must reach the threshold before
1946
a slow reseed will happen. Useful primarily when the generator is
1947
unseeded.
1948
1949
- Function: void yarrow256_force_reseed (struct yarrow256_ctx *CTX)
1950
Causes a slow reseed to take place immediately, regardless of the
1951
current entropy estimates of the two pools. Use with care.
1952
1953
Nettle includes an entropy estimator for one kind of input source:
1954
User keyboard input.
1955
1956
- Context struct: struct yarrow_key_event_ctx
1957
Information about recent key events.
1958
1959
- Function: void yarrow_key_event_init (struct yarrow_key_event_ctx
1960
*CTX)
1961
Initializes the context.
1962
1963
- Function: unsigned yarrow_key_event_estimate (struct
1964
yarrow_key_event_ctx *CTX, unsigned KEY, unsigned TIME)
1965
KEY is the id of the key (ASCII value, hardware key code, X
1966
keysym, ... it doesn't matter), and TIME is the timestamp of the
1967
event. The time must be given in units matching the resolution by
1968
which you read the clock. If you read the clock with microsecond
1969
precision, TIME should be provided in units of microseconds. But
1970
if you use `gettimeofday' on a typical Unix system where the clock
1971
ticks 10 or so microseconds at a time, TIME should be given in
1972
units of 10 microseconds.
1973
1974
Returns an entropy estimate, in bits, suitable for calling
1975
`yarrow256_update'. Usually, 0, 1 or 2 bits.
1976
1977
1978
File: nettle.info, Node: Miscellaneous functions, Next: Compatibility functions, Prev: Randomness, Up: Reference
1979
1980
Miscellaneous functions
1981
=======================
1982
1983
- Function: uint8_t * memxor (uint8_t *DST, const uint8_t *SRC, size_t
1984
N)
1985
XOR:s the source area on top of the destination area. The interface
1986
doesn't follow the Nettle conventions, because it is intended to be
1987
similar to the ANSI-C `memcpy' function.
1988
1989
`memxor' is declared in `<nettle/memxor.h>'.
1990
1991
1992
File: nettle.info, Node: Compatibility functions, Prev: Miscellaneous functions, Up: Reference
1993
1994
Compatibility functions
1995
=======================
1996
1997
For convenience, Nettle includes alternative interfaces to some
1998
algorithms, for compatibility with some other popular crypto toolkits.
1999
These are not fully documented here; refer to the source or to the
2000
documentation for the original implementation.
2001
2002
MD5 is defined in [RFC 1321], which includes a reference
2003
implementation. Nettle defines a compatible interface to MD5 in
2004
`<nettle/md5-compat.h>'. This file defines the typedef `MD5_CTX', and
2005
declares the functions `MD5Init', `MD5Update' and `MD5Final'.
2006
2007
Eric Young's "libdes" (also part of OpenSSL) is a quite popular DES
2008
implementation. Nettle includes a subset if it's interface in
2009
`<nettle/des-compat.h>'. This file defines the typedefs
2010
`des_key_schedule' and `des_cblock', two constants `DES_ENCRYPT' and
2011
`DES_DECRYPT', and declares one global variable `des_check_key', and
2012
the functions `des_cbc_cksum' `des_cbc_encrypt', `des_ecb2_encrypt',
2013
`des_ecb3_encrypt', `des_ecb_encrypt', `des_ede2_cbc_encrypt',
2014
`des_ede3_cbc_encrypt', `des_is_weak_key', `des_key_sched',
2015
`des_ncbc_encrypt' `des_set_key', and `des_set_odd_parity'.
2016
2017
2018
File: nettle.info, Node: Nettle soup, Next: Installation, Prev: Reference, Up: Top
2019
2020
Traditional Nettle Soup
2021
***********************
2022
2023
For the serious nettle hacker, here is a recipe for nettle soup. 4
2024
servings
2025
2026
1 liter fresh nettles (urtica dioica)
2027
2028
2 tablespoons butter
2029
2030
3 tablespoons flour
2031
2032
1 liter bouillon (meat or vegetable)
2033
2034
1/2 teaspoon salt
2035
2036
a tad white pepper
2037
2038
some cream or milk
2039
2040
Gather 1 liter fresh nettles. Use gloves! Small, tender shoots are
2041
preferable but the tops of larger nettles can also be used.
2042
2043
Rinse the nettles very well. Boil them for 10 minutes in lightly
2044
salted water. Strain the nettles and save the water. Hack the nettles.
2045
Melt the butter and mix in the flour. Dilute with bouillon and the
2046
nettle-water you save earlier. Add the hacked nettles. If you wish you
2047
can add some milk or cream at this stage. Bring to a boil and let boil
2048
for a few minutes. Season with salt and pepper.
2049
2050
Serve with boiled egg-halves.
2051
2052
2053
File: nettle.info, Node: Installation, Next: Index, Prev: Nettle soup, Up: Top
2054
2055
Installation
2056
************
2057
2058
Nettle uses `autoconf' and `automake'. To build it, unpack the source
2059
and run
2060
2061
./configure
2062
make
2063
make check
2064
make install
2065
2066
to install in the default location, `/usr/local'. The library is
2067
installed in `/use/local/lib/libnettle.a' and the include files are
2068
installed in `/use/local/include/nettle/'.
2069
2070
Only static libraries are installed.
2071
2072
2073
File: nettle.info, Node: Index, Prev: Installation, Up: Top
2074
2075
Function and Concept Index
2076
**************************
2077
2078
* Menu:
2079
2080
* aes_decrypt: Cipher functions.
2081
* aes_encrypt: Cipher functions.
2082
* aes_set_key: Cipher functions.
2083
* arcfour_crypt: Cipher functions.
2084
* arcfour_set_key: Cipher functions.
2085
* blowfish_decrypt: Cipher functions.
2086
* blowfish_encrypt: Cipher functions.
2087
* blowfish_set_key: Cipher functions.
2088
* cast128_decrypt: Cipher functions.
2089
* cast128_encrypt: Cipher functions.
2090
* cast128_set_key: Cipher functions.
2091
* CBC_CTX: Cipher Block Chaining.
2092
* CBC_DECRYPT: Cipher Block Chaining.
2093
* cbc_decrypt: Cipher Block Chaining.
2094
* CBC_ENCRYPT: Cipher Block Chaining.
2095
* cbc_encrypt: Cipher Block Chaining.
2096
* CBC_SET_IV: Cipher Block Chaining.
2097
* des3_decrypt: Cipher functions.
2098
* des3_encrypt: Cipher functions.
2099
* des3_set_key: Cipher functions.
2100
* des_decrypt: Cipher functions.
2101
* des_encrypt: Cipher functions.
2102
* des_fix_parity: Cipher functions.
2103
* des_set_key: Cipher functions.
2104
* dsa_generate_keypair: DSA.
2105
* dsa_private_key_clear: DSA.
2106
* dsa_private_key_init: DSA.
2107
* dsa_public_key_clear: DSA.
2108
* dsa_public_key_init: DSA.
2109
* dsa_sign: DSA.
2110
* dsa_sign_digest: DSA.
2111
* dsa_signature_clear: DSA.
2112
* dsa_signature_init: DSA.
2113
* dsa_verify: DSA.
2114
* dsa_verify_digest: DSA.
2115
* HMAC_CTX: Keyed hash functions.
2116
* HMAC_DIGEST: Keyed hash functions.
2117
* hmac_digest: Keyed hash functions.
2118
* hmac_md5_digest: Keyed hash functions.
2119
* hmac_md5_set_key: Keyed hash functions.
2120
* hmac_md5_update: Keyed hash functions.
2121
* HMAC_SET_KEY: Keyed hash functions.
2122
* hmac_set_key: Keyed hash functions.
2123
* hmac_sha1_digest: Keyed hash functions.
2124
* hmac_sha1_set_key: Keyed hash functions.
2125
* hmac_sha1_update: Keyed hash functions.
2126
* hmac_sha256_digest: Keyed hash functions.
2127
* hmac_sha256_set_key: Keyed hash functions.
2128
* hmac_sha256_update: Keyed hash functions.
2129
* hmac_update: Keyed hash functions.
2130
* md2_digest: Hash functions.
2131
* md2_init: Hash functions.
2132
* md2_update: Hash functions.
2133
* md4_digest: Hash functions.
2134
* md4_init: Hash functions.
2135
* md4_update: Hash functions.
2136
* md5_digest: Hash functions.
2137
* md5_init: Hash functions.
2138
* md5_update: Hash functions.
2139
* memxor: Miscellaneous functions.
2140
* rsa_compute_root: RSA.
2141
* rsa_generate_keypair: RSA.
2142
* rsa_md5_sign: RSA.
2143
* rsa_md5_sign_digest: RSA.
2144
* rsa_md5_verify: RSA.
2145
* rsa_md5_verify_digest: RSA.
2146
* rsa_private_key_clear: RSA.
2147
* rsa_private_key_init: RSA.
2148
* rsa_private_key_prepare: RSA.
2149
* rsa_public_key_clear: RSA.
2150
* rsa_public_key_init: RSA.
2151
* rsa_public_key_prepare: RSA.
2152
* rsa_sha1_sign: RSA.
2153
* rsa_sha1_sign_digest: RSA.
2154
* rsa_sha1_verify: RSA.
2155
* rsa_sha1_verify_digest: RSA.
2156
* serpent_decrypt: Cipher functions.
2157
* serpent_encrypt: Cipher functions.
2158
* serpent_set_key: Cipher functions.
2159
* sha1_digest: Hash functions.
2160
* sha1_init: Hash functions.
2161
* sha1_update: Hash functions.
2162
* sha256_digest: Hash functions.
2163
* sha256_init: Hash functions.
2164
* sha256_update: Hash functions.
2165
* twofish_decrypt: Cipher functions.
2166
* twofish_encrypt: Cipher functions.
2167
* twofish_set_key: Cipher functions.
2168
* yarrow256_force_reseed: Randomness.
2169
* yarrow256_init: Randomness.
2170
* yarrow256_is_seeded: Randomness.
2171
* yarrow256_needed_sources: Randomness.
2172
* yarrow256_random: Randomness.
2173
* yarrow256_seed: Randomness.
2174
* yarrow256_update: Randomness.
2175
* yarrow_key_event_estimate: Randomness.
2176
* yarrow_key_event_init: Randomness.
2177
2178
2179
2180
Tag Table:
2181
Node: Top1130
2182
Node: Introduction1834
2183
Node: Copyright3396
2184
Node: Conventions5884
2185
Node: Example7686
2186
Node: Reference8838
2187
Node: Hash functions9211
2188
Node: Cipher functions16960
2189
Node: Cipher Block Chaining35698
2190
Node: Keyed hash functions38807
2191
Node: Public-key algorithms46470
2192
Node: RSA50391
2193
Ref: RSA-Footnote-159396
2194
Node: DSA59565
2195
Node: Randomness67178
2196
Node: Miscellaneous functions82112
2197
Node: Compatibility functions82608
2198
Node: Nettle soup83846
2199
Node: Installation84839
2200
Node: Index85311
2201
2202
End Tag Table
Loggerhead is a web-based interface for Breezy
Version: 2.0.1