Commit 0c92a344 authored by Niels Möller's avatar Niels Möller

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

Rev: src/nettle/nettle.texinfo:1.6
parent ae0abe83
......@@ -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/}.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment