nettle.texinfo 32.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 15 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 91 92 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 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 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
\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

@set UPDATED-FOR 0.2

@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

@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.

And as the requirements of applications differ on subtle and not so
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
interfaces on top of Nettle, and share the code, testcases, banchmarks,
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. 

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

Nettle is distributed under the GNU General Public License (see the file
COPYING for details). However, many of the individual files are dual
licensed under less restrictive licenses like the GNU Lesser General
Public License, or public domain. Consult the headers in each file for
details.

It is conceivable that future versions will use the LGPL rather than the
GPL, mail me if you have questions or suggestions.

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
188
Nettle by Niels Möller. Released under the GPL.
Niels Möller's avatar
Niels Möller committed
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 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

@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
operating on the state. The context struct encapsulates all information
needed by the algorithm, and it can be copied or moved in memory with no
unexpected effects.

The functions for similar algorithms are 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 that doesn't show in function
prototypes, but which the application must nevertheless be aware of.
There is no difference between stream ciphers and block ciphers,
although they should be used quite differently by the application.

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
type @code{unsigned}, and a pointer of type @code{uint8_t *} or a
@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,
but they must not overlap in any other way.

@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::            
299
* Cipher Block Chaining::       
Niels Möller's avatar
Niels Möller committed
300 301 302 303 304 305 306 307 308 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 335 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 370 371 372 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
* Miscellaneous functions::     
@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,
message authentication codes, pseudo random generators, associating
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})
Extracts the 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.

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

416
@node Cipher functions, Cipher Block Chaining, Hash functions, Reference
Niels Möller's avatar
Niels Möller committed
417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444
@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.

To do this, you first initialize the cipher context for encryption or
decryption with a particular key, then use it to process plaintext och
ciphertext messages. The initialization is also 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.

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
445 446
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
447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 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

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
receive an encrypted message, 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
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.

@subsection AES
AES is a quite new block cipher, specified by NIST as a replacement for
the older DES standard. It is the result of a competition between cipher
designers, and the winning design, constructed by Joan Daemen and
Vincent Rijnmen. Before it won the competition, it was known under the
name RIJNDAEL.

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_BLOCK_SIZE
The ARCFOUR blocksize, 16
@end defvr

@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

593 594 595 596 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
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
632 633
@subsection BLOWFISH

634 635 636 637 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
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
675
@subsection DES
676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719
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
DES at all one should be using "triple DES", three DES ciphers piped
together, with three (or sometimes just two) independent keys.

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

@deftypefun int des_set_key (struct des_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 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
720 721

@subsection SERPENT
722 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
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
763 764

@subsection TWOFISH
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 797 798 799 800 801 802
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

803
@node Cipher Block Chaining, Miscellaneous functions, Cipher functions, Reference
804 805 806
@comment  node-name,  next,  previous,  up
@section Cipher Block Chaining

807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829
When using CBC mode, cleartext blocks are not encrypted independently of
each other, like in Electronic Cookbook mode. Instead, when encrypting a
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

830 831 832 833 834 835 836 837
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
838 839 840 841 842 843 844 845
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
846

847
There are also some macros to help use these functions correctly.
848

849
@deffn Macro CBC_CTX (@var{context_type}, @var{block_size})
850 851 852 853 854 855 856
Expands into
@example
@{
   context_type ctx;
   uint8_t iv[block_size];
@}
@end example
857 858 859 860
@end deffn

It can be used to define a CBC context stuct, either directly,

861 862 863 864 865 866 867 868 869 870
@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

871
@deffn Macro CBC_SET_IV (@var{ctx}, @var{iv})
872
First argument is a pointer to a context struct as defined by @code{CBC_CTX},
873 874 875
and the second is a pointer to an Initialization Vector (IV) that is
copied into that context.
@end deffn
876 877 878

@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})
879 880 881 882 883 884
A simpler way to invoke @code{cbc_encrypt} and @code{cbc_decrypt}. The first
argument is a context struct as defined by @code{CBC_CTX}, 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.
@end deffn
885

886 887 888
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.
889

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

891
@node Miscellaneous functions,  , Cipher Block Chaining, Reference
Niels Möller's avatar
Niels Möller committed
892 893 894
@comment  node-name,  next,  previous,  up
@section Miscellaneous functions

895 896 897 898 899 900
@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

Niels Möller's avatar
Niels Möller committed
901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927
@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

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