* nettle.texinfo: Added description of des3. Minor fixes.

Rev: src/nettle/nettle.texinfo:1.6

nettle.texinfo

@@ -12,7 +12,7 @@
 * Nettle: (nettle).           A low-level cryptographics library.
 @end direntry
 
-@set UPDATED-FOR 0.2
+@set UPDATED-FOR 1.0
 
 @c Latin-1 doesn't work with tex output.
 @c Also lookout for é characters.
@@ -88,6 +88,8 @@ translation approved by the Free Software Foundation.
 
 @end titlepage
 
+@contents
+
 @ifnottex
 @node     Top, Introduction, (dir), (dir)
 @comment  node-name,  next,  previous,  up
@@ -124,7 +126,7 @@ 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
+And as the requirements of applications differ in 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.
@@ -135,20 +137,24 @@ 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,
+interfaces on top of Nettle, and share the code, testcases, benchmarks,
 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. 
 
+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.
+
 @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
+COPYING for details). However, several 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.
+Public License, or are in the 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.
@@ -203,17 +209,18 @@ Released under the LGPL.
 
 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
+operating on the context. 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.
+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.
 
 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
@@ -225,12 +232,12 @@ 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
+type @code{unsigned}, and a pointer of type @code{uint8_t *} or
 @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.
+but they @emph{must not} overlap in any other way.
 
 @node Example, Reference, Conventions, Top
 @comment  node-name,  next,  previous,  up
@@ -324,7 +331,7 @@ 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
+message authentication codes, pseudo random generators, association of
 unique id:s to documents, and many other things.
 
 @subsection @acronym{MD5}
@@ -359,9 +366,9 @@ 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.
+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.
 
 This functions doesn't change the state in any way.
 @end deftypefun
@@ -423,13 +430,6 @@ 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
@@ -457,9 +457,9 @@ 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
+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
 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
@@ -482,12 +482,19 @@ 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.
 
+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.
+
 @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.
+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.
 
 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
@@ -559,10 +566,6 @@ 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
@@ -684,8 +687,7 @@ 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 at all one should be using DES3 or "triple DES", see below.
 
 DES also has some weak keys. Nettle defines DES in @file{<nettle/des.h>}.
 
@@ -700,7 +702,7 @@ The DES blocksize, 8
 DES key size, 8
 @end defvr
 
-@deftypefun int des_set_key (struct des_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{key})
+@deftypefun int des_set_key (struct des_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
@@ -718,6 +720,79 @@ in any other way.
 Analogous to @code{des_encrypt}
 @end deftypefun
 
+@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
+
 @subsection SERPENT
 SERPENT is one of the AES finalists, designed by Ross Anderson, Eli
 Biham and Lars Knudsen. Thus, the interface and properties are similar
@@ -805,7 +880,7 @@ Analogous to @code{twofish_encrypt}
 @section Cipher Block Chaining
 
 When using CBC mode, cleartext blocks are not encrypted independently of
-each other, like in Electronic Cookbook mode. Instead, when encrypting a
+each other, like in Electronic Cook Book 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
@@ -856,7 +931,7 @@ Expands into
 @end example
 @end deffn
 
-It can be used to define a CBC context stuct, either directly,
+It can be used to define a CBC context struct, either directly,
 
 @example
 struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;
@@ -876,11 +951,11 @@ copied into that context.
 
 @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})
-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.
+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.
 @end deffn
 
 These macros use some tricks to make the compiler display a warning if
@@ -898,6 +973,8 @@ doesn't follow the Nettle conventions, because it is intended to be
 similar to the ANSI-C @code{memcpy} function.
 @end deftypefun
 
+@code{memxor} is declared in @file{<nettle/memxor.h>}.
+
 @node Installation, Index, Reference, Top
 @comment  node-name,  next,  previous,  up
 @chapter Installation
@@ -912,6 +989,7 @@ make check
 make install
 @end example
 
+@noindent
 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/}.