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

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

@syncodeindex fn cp

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

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

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

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

Copyright 2001 @value{AUTHOR}

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

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

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

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

@end ifinfo

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

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

@author @value{AUTHOR}

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

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

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

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

@end titlepage

91 92
@contents

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

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

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

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

@end ifnottex

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#include <nettle/sha1.h>

#define BUF_SIZE 1000

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

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

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

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

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

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

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

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

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

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

@table @emph

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

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

@end table

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

@subsection @acronym{MD5}

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

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

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

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

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

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

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

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

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

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

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

@subsection @acronym{SHA1}

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

The functions are analogous to the MD5 ones.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@defvr Constant AES_MIN_KEY_SIZE
@end defvr

@defvr Constant AES_MAX_KEY_SIZE
@end defvr

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@subsection CAST128

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@dots{}

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

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

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

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

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

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

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

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

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

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

or to give it a struct tag,

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

Only static libraries are installed.

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

@printindex cp

@bye