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

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

Rev: src/nettle/nettle.texinfo:1.6
parent ae0abe83
...@@ -12,7 +12,7 @@ ...@@ -12,7 +12,7 @@
* Nettle: (nettle). A low-level cryptographics library. * Nettle: (nettle). A low-level cryptographics library.
@end direntry @end direntry
@set UPDATED-FOR 0.2 @set UPDATED-FOR 1.0
@c Latin-1 doesn't work with tex output. @c Latin-1 doesn't work with tex output.
@c Also lookout for é characters. @c Also lookout for é characters.
...@@ -88,6 +88,8 @@ translation approved by the Free Software Foundation. ...@@ -88,6 +88,8 @@ translation approved by the Free Software Foundation.
@end titlepage @end titlepage
@contents
@ifnottex @ifnottex
@node Top, Introduction, (dir), (dir) @node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up @comment node-name, next, previous, up
...@@ -124,7 +126,7 @@ cryptographic algorithms, you also need some way to keep track of available ...@@ -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 algorithms, their properties and variants. You often have some algorithm
selection process, often dictated by a protocol you want to implement. 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 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 in a different context. And that is why there are so many different
cryptographic libraries around. cryptographic libraries around.
...@@ -135,20 +137,24 @@ In particular, Nettle doesn't do algorithm selection. It doesn't do ...@@ -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. memory allocation. It doesn't do any I/O.
The idea is that one can build several application and context specific 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 documentation, etc. For this first version, the only application using
Nettle is LSH, and it uses an object-oriented abstraction on top of the Nettle is LSH, and it uses an object-oriented abstraction on top of the
library. 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 @node Copyright, Conventions, Introduction, Top
@comment node-name, next, previous, up @comment node-name, next, previous, up
@chapter Copyright @chapter Copyright
Nettle is distributed under the GNU General Public License (see the file 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 licensed under less restrictive licenses like the GNU Lesser General
Public License, or public domain. Consult the headers in each file for Public License, or are in the public domain. Consult the headers in each
details. file for details.
It is conceivable that future versions will use the LGPL rather than the It is conceivable that future versions will use the LGPL rather than the
GPL, mail me if you have questions or suggestions. GPL, mail me if you have questions or suggestions.
...@@ -203,17 +209,18 @@ Released under the LGPL. ...@@ -203,17 +209,18 @@ Released under the LGPL.
For each supported algorithm, there is an include file that defines a For each supported algorithm, there is an include file that defines a
@emph{context struct}, a few constants, and declares functions for @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 needed by the algorithm, and it can be copied or moved in memory with no
unexpected effects. unexpected effects.
The functions for similar algorithms are similar, but there are some For consistency, functions for different algorithms are very similar,
differences, for instance reflecting if the key setup or encryption but there are some differences, for instance reflecting if the key setup
function differ for encryption and encryption, and whether or not key or encryption function differ for encryption and encryption, and whether
setup can fail. There are also differences that doesn't show in function or not key setup can fail. There are also differences between algorithms
prototypes, but which the application must nevertheless be aware of. that don't show in function prototypes, but which the application must
There is no difference between stream ciphers and block ciphers, nevertheless be aware of. There is no big difference between the
although they should be used quite differently by the application. 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 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 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 ...@@ -225,12 +232,12 @@ like @code{FOO_BLOCK_SIZE} (a constant) and @code{foo_set_key} (a
function). function).
In all functions, strings are represented with an explicit length, of 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 @code{const uint8_t *}. For functions that transform one string to
another, the argument order is length, destination pointer and source another, the argument order is length, destination pointer and source
pointer. Source and destination areas are of the same length. Source and 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, 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 @node Example, Reference, Conventions, Top
@comment node-name, next, previous, up @comment node-name, next, previous, up
...@@ -324,7 +331,7 @@ that @code{H(x)} = @code{H(y)}. ...@@ -324,7 +331,7 @@ that @code{H(x)} = @code{H(y)}.
@end table @end table
Hash functions are useful as building blocks for digital signatures, 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. unique id:s to documents, and many other things.
@subsection @acronym{MD5} @subsection @acronym{MD5}
...@@ -359,9 +366,9 @@ processed with @code{md5_update}. ...@@ -359,9 +366,9 @@ processed with @code{md5_update}.
@end deftypefun @end deftypefun
@deftypefun void md5_digest (struct md5_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) @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 Extracts the message digest, writing it to @var{digest}. @var{length}
@code{MD5_DIGEST_SIZE}, in which case only the first @var{length} octets may be smaller than @code{MD5_DIGEST_SIZE}, in which case only the first
of the digest are written. @var{length} octets of the digest are written.
This functions doesn't change the state in any way. This functions doesn't change the state in any way.
@end deftypefun @end deftypefun
...@@ -423,13 +430,6 @@ only the ciphertext, but not the key, it should be hard to find the ...@@ -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 cleartext. Given matching pairs of plaintext and ciphertext, it should
be hard to find the key. 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. There are two main classes of ciphers: Block ciphers and stream ciphers.
A block cipher can process data only in fixed size chunks, called 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. ...@@ -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 A common misconception is that encryption, by itself, implies
authentication. Say that you and a friend share a secret key, and you 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 receive an encrypted message. You apply the key, and get a cleartext
that makes sense to you. Can you then be sure that it really was your message that makes sense to you. Can you then be sure that it really was
friend that wrote the message you're reading? The anser is no. For 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 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 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 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 ...@@ -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 have weak keys. There are several good ciphers that don't have any weak
keys. 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 @subsection AES
AES is a quite new block cipher, specified by NIST as a replacement for 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 the older DES standard. The standarad is the result of a competition
designers, and the winning design, constructed by Joan Daemen and between cipher designers. The winning design, also known as RIJNDAEL,
Vincent Rijnmen. Before it won the competition, it was known under the was constructed by Joan Daemen and Vincent Rijnmen.
name RIJNDAEL.
Like all the AES candidates, the winning design uses a block size of 128 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 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>}. ...@@ -559,10 +566,6 @@ Nettle defines ARCFOUR in @file{<nettle/arcfour.h>}.
@deftp {Context struct} {struct arcfour_ctx} @deftp {Context struct} {struct arcfour_ctx}
@end deftp @end deftp
@defvr Constant ARCFOUR_BLOCK_SIZE
The ARCFOUR blocksize, 16
@end defvr
@defvr Constant ARCFOUR_MIN_KEY_SIZE @defvr Constant ARCFOUR_MIN_KEY_SIZE
Minimum key size, 1 Minimum key size, 1
@end defvr @end defvr
...@@ -684,8 +687,7 @@ key. ...@@ -684,8 +687,7 @@ key.
The key size of DES is so small that keys can be found by brute force, 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 using specialized hardware or lots of ordinary work stations in
parallell. One shouldn't be using plain DES at all today, if one uses 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 DES at all one should be using DES3 or "triple DES", see below.
together, with three (or sometimes just two) independent keys.
DES also has some weak keys. Nettle defines DES in @file{<nettle/des.h>}. DES also has some weak keys. Nettle defines DES in @file{<nettle/des.h>}.
...@@ -700,7 +702,7 @@ The DES blocksize, 8 ...@@ -700,7 +702,7 @@ The DES blocksize, 8
DES key size, 8 DES key size, 8
@end defvr @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 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 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 parity. Calling @code{des_encrypt} or @code{des_decrypt} with a bad key
...@@ -718,6 +720,79 @@ in any other way. ...@@ -718,6 +720,79 @@ in any other way.
Analogous to @code{des_encrypt} Analogous to @code{des_encrypt}
@end deftypefun @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 @subsection SERPENT
SERPENT is one of the AES finalists, designed by Ross Anderson, Eli SERPENT is one of the AES finalists, designed by Ross Anderson, Eli
Biham and Lars Knudsen. Thus, the interface and properties are similar Biham and Lars Knudsen. Thus, the interface and properties are similar
...@@ -805,7 +880,7 @@ Analogous to @code{twofish_encrypt} ...@@ -805,7 +880,7 @@ Analogous to @code{twofish_encrypt}
@section Cipher Block Chaining @section Cipher Block Chaining
When using CBC mode, cleartext blocks are not encrypted independently of 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 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 cleartext before it is fed to the block cipher. When encrypting the
first block, a random block called an @dfn{IV}, or Initialization first block, a random block called an @dfn{IV}, or Initialization
...@@ -856,7 +931,7 @@ Expands into ...@@ -856,7 +931,7 @@ Expands into
@end example @end example
@end deffn @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 @example
struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx; struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;
...@@ -876,11 +951,11 @@ copied into that context. ...@@ -876,11 +951,11 @@ copied into that context.
@deffn Macro CBC_ENCRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) @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}) @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 A simpler way to invoke @code{cbc_encrypt} and @code{cbc_decrypt}. The
argument is a context struct as defined by @code{CBC_CTX}, the second first argument is a pointer to a context struct as defined by
argument is an encryption or decryption function following Nettle's @code{CBC_CTX}, and the second argument is an encryption or decryption
conventions. The last three arguments define the source and destination function following Nettle's conventions. The last three arguments define
area for the operation. the source and destination area for the operation.
@end deffn @end deffn
These macros use some tricks to make the compiler display a warning if 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 ...@@ -898,6 +973,8 @@ doesn't follow the Nettle conventions, because it is intended to be
similar to the ANSI-C @code{memcpy} function. similar to the ANSI-C @code{memcpy} function.
@end deftypefun @end deftypefun
@code{memxor} is declared in @file{<nettle/memxor.h>}.
@node Installation, Index, Reference, Top @node Installation, Index, Reference, Top
@comment node-name, next, previous, up @comment node-name, next, previous, up
@chapter Installation @chapter Installation
...@@ -912,6 +989,7 @@ make check ...@@ -912,6 +989,7 @@ make check
make install make install
@end example @end example
@noindent
to install in the default location, @file{/usr/local}. The library is 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/lib/libnettle.a} and the include files are
installed in @file{/use/local/include/nettle/}. 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