From 0c92a344f2b2ce0e735a2b4ff489e986db975770 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niels=20M=C3=B6ller?= <nisse@lysator.liu.se>
Date: Sun, 16 Sep 2001 23:35:17 +0200
Subject: [PATCH] * nettle.texinfo: Added description of des3. Minor fixes.
Rev: src/nettle/nettle.texinfo:1.6
---
nettle.texinfo | 174 +++++++++++++++++++++++++++++++++++--------------
1 file changed, 126 insertions(+), 48 deletions(-)
diff --git a/nettle.texinfo b/nettle.texinfo
index 9bef52b8..105c6298 100644
--- a/nettle.texinfo
+++ b/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/}.
--
GitLab