nettle.texinfo

@end example

Nettle includes a few utility functions for applying a block cipher in
Cipher Block Chaining (@acronym{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 @acronym{CBC}
mode. The 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

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

@deffn Macro CBC_CTX (@var{context_type}, @var{block_size})
Expands into
@example
@{
   context_type ctx;
   uint8_t iv[block_size];
@}
@end example
@end deffn

It can be used to define a @acronym{CBC} context struct, either directly,

@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

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

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


@node Keyed hash functions, Public-key algorithms, Cipher Block Chaining, Reference
@comment  node-name,  next,  previous,  up
@section Keyed Hash Functions

A @dfn{keyed hash function}, or @dfn{Message Authentication Code}
(@acronym{MAC}) is a function that takes a key and a message, and
produces fixed size @acronym{MAC}. It should be hard to compute a
message and a matching @acronym{MAC} without knowledge of the key. It
should also be hard to compute the key given only messages and
corresponding @acronym{MAC}s.

Keyed hash functions are useful primarily for message authentication,
when the Alice and Bob shares a secret: The sender, Alice, computes the
@acronym{MAC} and attaches it to the message. The receiver, Bob, also computes
the @acronym{MAC} of the message, using the same key, and compares that
to Alice's value. If they match, Bob can be assured that
the message has not been modified on it's way from Alice.

However, unlike digital signatures, this assurance is not transferable.
Bob can't show the message and the @acronym{MAC} to a third party and
prove that Alice sent that message. Not even if he gives away the key to
the third party. The reason is that the @emph{same} key is used on both
sides, and anyone knowing the key can create a correct @acronym{MAC} for
any message. If Bob believes that only he and Alice knows the key, and
he knows that he didn't attach a @acronym{MAC} to a particular message,
he knows it must be Alice who did it. However, the third party can't
distinguish between @acronym{MAC} created by Alice and one created by
Bob.

Keyed hash functions are typically a lot faster than digital signatures
as well.

@subsection @acronym{HMAC}

One can build keyed hash functions from ordinary hash functions. Older
constructions simply concatenate secret key and message and hashes that, but
such constructions have weaknesses. A better construction is
@acronym{HMAC}, described in @cite{RFC 2104}.

For an underlying hash function @code{H}, with digest size @code{l} and
internal block size @code{b}, @acronym{HMAC-H} is constructed as
follows: From a given key @code{k}, two distinct subkeys @code{k_i} and
@code{k_o} are constructed, both of length @code{b}. The
@acronym{HMAC-H} of a message @code{m} is then computed as @code{H(k_o |
H(k_i | m))}, where @code{|} denotes string concatenation.

@acronym{HMAC} keys can be of any length, but it is recommended to use
keys of length @code{l}, the digest size of the underlying hash function
@code{H}. Keys that are longer than @code{b} are shortened to length
@code{l} by hashing with @code{H}, so arbitrarily long keys aren't
very useful. 

Nettle's @acronym{HMAC} functions are defined in @file{<nettle/hmac.h>}.
There are abstract functions that use a pointer to a @code{struct
nettle_hash} to represent the underlying hash function and @code{void
*} pointers that point to three different context structs for that hash
function. There are also concrete functions for @acronym{HMAC-MD5},
@acronym{HMAC-SHA1}, and @acronym{HMAC-SHA256}. First, the abstract
functions:

@deftypefun void hmac_set_key (void *@var{outer}, void *@var{inner}, void *@var{state}, const struct nettle_hash *@var{H}, unsigned @var{length}, const uint8_t *@var{key})
Initializes the three context structs from the key. The @var{outer} and
@var{inner} contexts corresponds to the subkeys @code{k_o} and
@code{k_i}. @var{state} is used for hashing the message, and is
initialized as a copy of the @var{inner} context.
@end deftypefun

@deftypefun void hmac_update(void *@var{state}, const struct nettle_hash *@var{H}, unsigned @var{length}, const uint8_t *@var{data})
This function is called zero or more times to process the message.
Actually, @code{hmac_update(state, H, length, data)} is equivalent to
@code{H->update(state, length, data)}, so if you wish you can use the
ordinary update function of the underlying hash function instead.
@end deftypefun

@deftypefun void hmac_digest (const void *@var{outer}, const void *@var{inner}, void *@var{state}, const struct nettle_hash *@var{H}, unsigned @var{length}, uint8_t *@var{digest})
Extracts the @acronym{MAC} of the message, writing it to @var{digest}.
@var{outer} and @var{inner} are not modified. @var{length} is usually
equal to @code{H->digest_size}, but if you provide a smaller value,
only the first @var{length} octets of the @acronym{MAC} are written.

This function also resets the @var{state} context so that you can start
over processing a new message (with the same key).
@end deftypefun

Like for @acronym{CBC}, there are some macros to help use these
functions correctly.

@deffn Macro HMAC_CTX (@var{type})
Expands into
@example
@{
   type outer;
   type inner;
   type state;
@}
@end example
@end deffn

It can be used to define a @acronym{HMAC} context struct, either
directly,

@example
struct HMAC_CTX(struct md5_ctx) ctx;
@end example

or to give it a struct tag,

@example
struct hmac_md5_ctx HMAC_CTX (struct md5_ctx);
@end example

@deffn Macro HMAC_SET_KEY (@var{ctx}, @var{H}, @var{length}, @var{key})
@var{ctx} is a pointer to a context struct as defined by
@code{HMAC_CTX}, @var{H} is a pointer to a @code{const struct
nettle_hash} describing the underlying hash function (so it must match
the type of the components of @var{ctx}). The last two arguments specify
the secret key.
@end deffn

@deffn Macro HMAC_DIGEST (@var{ctx}, @var{H}, @var{length}, @var{digest})
@var{ctx} is a pointer to a context struct as defined by
@code{HMAC_CTX}, @var{H} is a pointer to a @code{const struct
nettle_hash} describing the underlying hash function. The last two
arguments specify where the digest is written.
@end deffn

Note that there is no @code{HMAC_UPDATE} macro; simply call hmac_update
function directly, or the update function of the underlying hash function.

@subsection Concrete @acronym{HMAC} functions
Now we come to the specialized @acronym{HMAC} functions, which are
easier to use than the general @acronym{HMAC} functions.

@subsubsection @acronym{HMAC-MD5}

@deftp {Context struct} {struct hmac_md5_ctx}
@end deftp

@deftypefun void hmac_md5_set_key (struct hmac_md5_ctx *@var{ctx}, unsigned @var{key_length}, const uint8_t *@var{key})
Initializes the context with the key.
@end deftypefun

@deftypefun void hmac_md5_update (struct hmac_md5_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
Process some more data.
@end deftypefun

@deftypefun void hmac_md5_digest (struct hmac_md5_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
Extracts the @acronym{MAC}, 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 @acronym{MAC} are written.

This function also resets the context for processing new messages, with
the same key.
@end deftypefun

@subsubsection @acronym{HMAC-SHA1}

@deftp {Context struct} {struct hmac_sha1_ctx}
@end deftp

@deftypefun void hmac_sha1_set_key (struct hmac_sha1_ctx *@var{ctx}, unsigned @var{key_length}, const uint8_t *@var{key})
Initializes the context with the key.
@end deftypefun

@deftypefun void hmac_sha1_update (struct hmac_sha1_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
Process some more data.
@end deftypefun

@deftypefun void hmac_sha1_digest (struct hmac_sha1_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
Extracts the @acronym{MAC}, 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 @acronym{MAC} are written.

This function also resets the context for processing new messages, with
the same key.
@end deftypefun


@subsubsection @acronym{HMAC-SHA256}

@deftp {Context struct} {struct hmac_sha256_ctx}
@end deftp

@deftypefun void hmac_sha256_set_key (struct hmac_sha256_ctx *@var{ctx}, unsigned @var{key_length}, const uint8_t *@var{key})
Initializes the context with the key.
@end deftypefun

@deftypefun void hmac_sha256_update (struct hmac_sha256_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
Process some more data.
@end deftypefun

@deftypefun void hmac_sha256_digest (struct hmac_sha256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
Extracts the @acronym{MAC}, writing it to @var{digest}. @var{length} may be smaller than
@code{SHA256_DIGEST_SIZE}, in which case only the first @var{length}
octets of the @acronym{MAC} are written.

This function also resets the context for processing new messages, with
the same key.
@end deftypefun

@node Public-key algorithms, Randomness, Keyed hash functions, Reference
@comment  node-name,  next,  previous,  up
@section Public-key algorithms

Nettle uses @acronym{GMP}, the GNU bignum library, for all calculations
with large numbers. In order to use the public-key features of Nettle,
you must install @acronym{GMP}, at least version 3.0, before compiling
Nettle, and you need to link your programs with @code{-lgmp}.

The concept of @dfn{Public-key} encryption and digital signatures was
discovered by Whitfield Diffie and Martin E. Hellman and described in a
paper 1976. In traditional, "symmetric", cryptography, sender and
receiver share the same keys, and these keys must be distributed in a
secure way. And if there are many users or entities that need to
communicate, each @emph{pair} needs a shared secret key known by nobody
else.

Public-key cryptography uses trapdoor one-way functions. A
@dfn{one-way function} is a function @code{F} such that it is easy to
compute the value @code{F(x)} for any @code{x}, but given a value
@code{y}, it is hard to compute a corresponding @code{x} such that
@code{y = F(x)}. Two examples are cryptographic hash functions, and
exponentiation in certain groups.

A @dfn{trapdoor one-way function} is a function @code{F} that is
one-way, unless one knows some secret information about @code{F}. If one
knows the secret, it is easy to compute both @code{F} and it's inverse.
If this sounds strange, look at the @acronym{RSA} example below.

Two important uses for one-way functions with trapdoors are public-key
encryption, and digital signatures. Of these, I won't say more about
public-key encryption, as that isn't yet supported by Nettle. So the
rest of this chapter is about digital signatures.

To use a digital signature algorithm, one must first create a
@dfn{key-pair}: A public key and a corresponding private key. The private
key is used to sign messages, while the public key is used for verifying
that that signatures and messages match. Some care must be taken when
distributing the public key; it need not be kept secret, but if a bad
guy is able to replace it (in transit, or in some user's list of known
public keys), bad things may happen.

There are two operations one can do with the keys. The signature
operation takes a message and a private key, and creates a signature for
the message. A signature is some string of bits, usually at most a few
thousand bits or a few hundred octets. Unlike paper-and-ink signatures,
the digital signature depends on the message, so one can't cut it out of
context and glue it to a different message.

The verification operation takes a public key, a message, and a string
that is claimed to be a signature on the message, and returns true or
false. If it returns true, that means that the three input values
matched, and the verifier can be sure that someone went through with the
signature operation on that very message, and that the "someone" also
knows the private key corresponding to the public key.

The desired properties of a digital signature algorithm are as follows:
Given the public key and pairs of messages and valid signatures on them,
it should be hard to compute the private key, and it should also be hard
to create a new message and signature that is accepted by the
verification operation.

Besides signing meaningful messages, digital signatures can be used for
authorization. A server can be configured with a public key, such that
any client that connects to the service is given a random nonce message.
If the server gets a reply with a correct signature matching the nonce
message and the configured public key, the client is granted access. So
the configuration of the server can be understood as "grant access to
whoever knows the private key corresponding to this particular public
key, and to no others".

@subsection @acronym{RSA}

The @acronym{RSA} was the first practical digital signature algorithm
that was constructed. It was described 1978 in a paper by Ronald Rivest,
Adi Shamir and L.M. Adleman, and the technique was also patented in
1983. The patent expired on September 20, 2000, and since that day,
@acronym{RSA} can be used freely.

It's remarkably simple to describe the trapdoor function behind
@acronym{RSA}. The "one-way"-function used is

@example
F(x) = x^e mod n
@end example

I.e. raise x to the @code{e}:th power, while discarding all multiples of
@code{n}. The pair of numbers @code{n} and @code{e} is the public key.
@code{e} can be quite small, even @code{e = 3} has been used, although
slightly larger numbers are recommended. @code{n} should be about 1000
bits or larger.

If @code{n} is large enough, and properly chosen, the inverse of F,
the computation of @code{e}:th roots modulo @code{n}, is very difficult.
But, where's the trapdoor?

Let's first look at how @acronym{RSA} key-pairs are generated. First
@code{n} is chosen as the product of two large prime numbers @code{p}
and @code{q} of roughly the same size (so if @code{n} is 1000 bits,
@code{p} and @code{q} are about 500 bits each). One also computes the
number @code{phi = (p-1)(q-1)}, in mathematical speak, phi is the order
of the multiplicative group of integers modulo n.

Next, @code{e} is chosen. It must have no factors in common with phi (in
particular, it must be odd), but can otherwise be chosen more or less
randomly. @code{e = 65537} is a popular choice, because it makes raising
to the @code{e}:th power particularly efficient, and being prime, it
usually has no factors common with @code{phi}.

Finally, a number @code{d}, @code{d < n} is computed such that @code{e d
mod phi = 1}. It can be shown that such a number exists (this is why
@code{e} and @code{phi} must have no common factors), and that for all x,

@example
(x^e)^d mod n = x^(ed) mod n = (x^d)^e mod n = x
@end example

Using Euclid's algorithm, @code{d} can be computed quite easily from
@code{phi} and @code{e}. But it is still hard to get @code{d} without
knowing @code{phi}, which depends on the factorization of @code{n}.

So @code{d} is the trapdoor, if we know @code{d} and @code{y = F(x)}, we can
recover x as @code{y^d mod n}. @code{d} is also the private half of
the @acronym{RSA} key-pair.

The most common signature operation for @acronym{RSA} is defined in
@cite{PKCS#1}, a specification by RSA Laboratories. The message to be
signed is first hashed using a cryptographic hash function, e.g.
@acronym{MD5} or @acronym{SHA1}. Next, some padding, the @acronym{ASN.1}
"Algorithm Identifier" for the hash function, and the message digest
itself, are concatenated and converted to a number @code{x}. The
signature is computed from @code{x} and the private key as @code{s = x^d
mod n}@footnote{Actually, the computation is not done like this, it is
done more efficiently using @code{p}, @code{q} and the Chinese remainder
theorem (@acronym{CRT}). But the result is the same.}. The signature, @code{s} is a
number of about the same size of @code{n}, and it usually encoded as a
sequence of octets, most significant octet first.

The verification operation is straight-forward, @code{x} is computed
from the message in the same way as above. Then @code{s^e mod n} is
computed, the operation returns true if and only if the result equals
@code{x}.

@subsection Nettle's @acronym{RSA} support

Nettle represents @acronym{RSA} keys using two structures that contain
large numbers (of type @code{mpz_t}).

@deftp {Context struct} {rsa_public_key} size n e
@code{size} is the size, in octets, of the modulo, and is used internally.
@code{n} and @code{e} is the public key.
@end deftp

@deftp {Context struct} {rsa_private_key} size d p q a b c
@code{size} is the size, in octets, of the modulo, and is used internally.
@code{d} is the secret exponent, but it is not actually used when
signing. Instead, the factors @code{p} and @code{q}, and the parameters
@code{a}, @code{b} and @code{c} are used. They are computed from @code{p},
@code{q} and @code{d} such that @code{a e mod (p - 1) = 1, b e mod (q -
1) = 1, c q mod p= 1}.
@end deftp

Before use, these structs must be initialized by calling one of

@deftypefun void rsa_init_public_key (struct rsa_public_key *@var{pub})
@deftypefunx void rsa_init_private_key (struct rsa_private_key *@var{key})
Calls @code{mpz_init} on all numbers in the key struct.
@end deftypefun

and when finished with them, the space for the numbers must be
deallocated by calling one of

@deftypefun void rsa_clear_public_key (struct rsa_public_key *@var{pub})
@deftypefunx void rsa_clear_private_key (struct rsa_private_key *@var{key})
Calls @code{mpz_clear} on all numbers in the key struct.
@end deftypefun

In general, Nettle's @acronym{rsa} functions deviates from Nettle's "no
memory allocation"-policy. Space for all the numbers, both in the key structs
above, and temporaries, are allocated dynamically. For information on how
to customize allocation, see
@xref{Custom Allocation,,GMP Allocation,gmp, GMP Manual}.

When you have assigned values to the attributes of a key, you must call

@deftypefun int rsa_prepare_public_key (struct rsa_public_key *@var{pub})
@deftypefunx int rsa_prepare_private_key (struct rsa_private_key *@var{key})
Computes the octet size of the key (stored in the @code{size} attribute,
and may also do other basic sanity checks. Returns one if successful, or
zero if the key can't be used, for instance if the modulo is smaller
than the minimum size specified by PKCS#1.
@end deftypefun

Before signing or verifying a message, you first hash it with the
appropriate hash function. You pass the hash function's context struct
to the rsa function, and it will extract the message digest and do the
rest of the work.

Creation and verification of signatures is done with the following functions:

@deftypefun void rsa_md5_sign (struct rsa_private_key *@var{key}, struct md5_ctx *@var{hash}, mpz_t @var{signature})
@deftypefunx void rsa_sha1_sign (struct rsa_private_key *@var{key}, struct sha1_ctx *@var{hash}, mpz_t @var{signature})
The signature is stored in @var{signature} (which must have been
@code{mpz_init}:ed earlier). The hash context is reset so that it can be
used for new messages.
@end deftypefun

@deftypefun int rsa_md5_verify (struct rsa_public_key *@var{key}, struct md5_ctx *@var{hash}, const mpz_t @var{signature})
@deftypefunx int rsa_sha1_verify (struct rsa_public_key *@var{key}, struct sha1_ctx *@var{hash}, const mpz_t @var{signature})
Returns 1 if the signature is valid, or 0 if it isn't. In either case,
the hash context is reset so that it can be used for new messages.
@end deftypefun

If you need to use the @acronym{RSA} trapdoor, the private key, in a way
that isn't supported by the above functions Nettle also includes a
function that computes @code{x^d mod n} and nothing more, using the
@acronym{CRT} optimization.

@deftypefun void rsa_compute_root (struct rsa_private_key *@var{key}, mpz_t @var{x}, const mpz_t @var{m})
Computes @code{x = m^d}, efficiently.
@end deftypefun

At last, how do you create new keys?

@deftypefun int rsa_generate_keypair (struct rsa_public_key *@var{pub}, struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, void *@var{progress_ctx}, nettle_progress_func @var{progress}, unsigned @var{n_size}, unsigned @var{e_size});
There are lots of parameters. @var{pub} and @var{key} is where the
resulting key pair is stored. The structs should be initialized, but you
don't need to call @code{rsa_prepare_public_key} or
@code{rsa_prepare_private_key} after key generation.

@var{random_ctx} and @var{random} is a randomness generator.
@code{random(random_ctx, length, dst)} should generate @code{length}
random octets and store them at @code{dst}. For advice, see
@xref{Randomness}.

@var{progress} and @var{progress_ctx} can be used to get callbacks
during the key generation process, in order to uphold an illusion of
progress. @var{progress} can be NULL, in that case there are no
callbacks.

@var{size_n} is the desired size of the modulo, in bits. If @var{size_e}
is non-zero, it is the desired size of the public exponent and a random
exponent of that size is selected. But if @var{e_size} is zero, it is
assumed that the caller has already chosen a value for @code{e}, and
stored it in @var{pub}.

Returns 1 on success, and 0 on failure. The function can fail for
example if if @var{n_size} is too small, or if @var{e_size} is zero and
@code{pub->e} is an even number.
@end deftypefun

@node Randomness, Miscellaneous functions, Public-key algorithms, Reference
@comment  node-name,  next,  previous,  up
@section Randomness

A crucial ingredient in many cryptographic contexts is randomness: Let
@code{p} be a random prime, choose a random initialization vector
@code{iv}, a random key @code{k} and a random exponent @code{e}, etc. In
the theories, it is assumed that you have plenty of randomness around.
If this assumption is not true in practice, systems that are otherwise
perfectly secure, can be broken. Randomness has often turned out to be
the weakest link in the chain.

In non-cryptographic applications, such as games as well as scientific
simulation, a good randomness generator usually means a generator that
has good statistical properties, and is seeded by some simple function
of things like the current time, process id, and host name.

However, such a generator is inadequate for cryptography, for at least
two reasons:

@itemize

@item
It's too easy for an attacker to guess the initial seed. Even if it will
take some 2^32 tries before he guesses right, that's far too easy. For
example, if the process id is 16 bits, the resolution of "current time"
is one second, and the attacker knows what day the generator was seeded,
there are only about 2^32 possibilities to try if all possible values
for the process id and time-of-day are tried.

@item
The generator output reveals too much. By observing only a small segment
of the generator's output, its internal state can be recovered, and from
there, all previous output and all future output can be computed by the
attacker. 
@end itemize

A randomness generator that is used for cryptographic purposes must have
better properties. Let's first look at the seeding, as the issues here
are mostly independent of the rest of the generator. The initial state
of the generator (its seed) must be unguessable by the attacker. So
what's unguessable? It depends on what the attacker already knows. The
concept used in information theory to reason about such things is called
"entropy", or "conditional entropy" (not to be confused with the
thermodynamic concept with the same name). A reasonable requirement is
that the seed contains a conditional entropy of at least some 80-100
bits. This property can be explained as follows: Allow the attacker to
ask @code{n} yes-no-questions, of his own choice, about the seed. If
the attacker, using this question-and-answer session, as well as any
other information he knows about the seeding process, still can't guess
the seed correctly, then the conditional entropy is more than @code{n}
bits.

Let's look at an example. Say information about timing of received
network packets is used in the seeding process. If there is some random
network traffic going on, this will contribute some bits of entropy or
"unguessability" to the seed. However, if the attacker can listen in to
the local network, or if all but a small number of the packets were
transmitted by machines that the attacker can monitor, this additional
information makes the seed easier for the attacker to figure out. Even
if the information is exactly the same, the conditional entropy, or
unguessability, is smaller for an attacker that knows some of it already
before the hypothetical question-and-answer session.

Seeding of good generators is usually based on several sources. The key
point here is that the amount of unguessability that each source
contributes, depends on who the attacker is. Some sources that have been
used are:

@table @asis
@item High resolution timing of i/o activities
Such as completed blocks from spinning hard disks, network packets, etc.
Getting access to such information is quite system dependent, and not
all systems include suitable hardware. If available, it's one of the
better randomness source one can find in a digital, mostly predictable,
computer.

@item User activity
Timing and contents of user interaction events is another popular source
that is available for interactive programs (even if I suspect that it is
sometimes used in order to make the user feel good, not because the
quality of the input is needed or used properly). Obviously, not
available when a machine is unattended. Also beware of networks: User
interaction that happens across a long serial cable, @acronym{TELNET}
session, or even @acronym{SSH} session may be visible to an attacker, in
full or partially.

@item Audio input
Any room, or even a microphone input that's left unconnected, is a
source of some random background noise, which can be fed into the
seeding process.

@item Specialized hardware
Hardware devices with the sole purpose of generating random data have
been designed. They range from radioactive samples with an attached
Geiger counter, to amplification of the inherent noise in electronic
components such as diodes and resistors, to low-frequency sampling of
chaotic systems. Hashing successive images of a Lava lamp is a
spectacular example of the latter type.

@item Secret information
Secret information, such as user passwords or keys, or private files
stored on disk, can provide some unguessability. A problem is that if
the information is revealed at a later time, the unguessability
vanishes. Another problem is that this kind of information tends to be
fairly constant, so if you rely on it and seed your generator regularly,
you risk constructing almost similar seeds or even constructing the same
seed more than once.
@end table

For all practical sources, it's difficult but important to provide a
reliable lower bound on the amount of unguessability that it provides.
Two important points are to make sure that the attacker can't observe
your sources (so if you like the Lava lamp idea, remember that you have
to get your own lamp, and not put it by a window or anywhere else where
strangers can see it), and that hardware failures are detected. What if
the bulb in the Lava lamp, which you keep locked into a cupboard
following the above advice, breaks after a few months?

So let's assume that we have been able to find an unguessable seed,
which contains at least 80 bits of conditional entropy, relative to all
attackers that we care about (typically, we must at the very least
assume that no attacker has root privileges on our machine).

How do we generate output from this seed, and how much can we get? Some
generators (notably the Linux @file{/dev/random} generator) tries to
estimate available entropy and restrict the amount of output. The goal
is that if you read 128 bits from @file{/dev/random}, you should get 128
"truly random" bits. This is a property that is useful in some
specialized circumstances, for instance when generating key material for
a one time pad, or when working with unconditional blinding, but in most
cases, it doesn't matter much. For most application, there's no limit on
the amount of useful "random" data that we can generate from a small
seed; what matters is that the seed is unguessable and that the
generator has good cryptographic properties.

At the heart of all generators lies its internal state. Future output
is determined by the internal state alone. Let's call it the generator's
key. The key is initialized from the unguessable seed. Important
properties of a generator are:

@table @dfn

@item Key-hiding
An attacker observing the output should not be able to recover the
generator's key.

@item Independence of outputs
Observing some of the output should not help the attacker to guess
previous or future output.

@item Forward secrecy
Even if an attacker compromises the generator's key, he should not be
able to guess the generator output @emph{before} the key compromise.

@item Recovery from key compromise
If an attacker compromises the generator's key, he can compute
@emph{all} future output. This is inevitable if the generator is seeded
only once, at startup. However, the generator can provide a reseeding
mechanism, to achieve recovery from key compromise. More precisely: If
the attacker compromises the key at a particular time @code{t_1}, there
is another later time @code{t_2}, such that if the attacker observes all
output generated between @code{t_1} and @code{t_2}, he still can't guess
what output is generated after @code{t_2}.

@end table

Nettle includes one randomness generator that is believed to have all
the above properties, and two simpler ones.

@acronym{ARCFOUR}, like any stream cipher, can be used as a randomness
generator. Its output should be of reasonable quality, if the seed is
hashed properly before it is used with @code{arcfour_set_key}. There's
no single natural way to reseed it, but if you need reseeding, you
should be using Yarrow instead.

The "lagged Fibonacci" generator in @file{<nettle/knuth-lfib.h>} is a
fast generator with good statistical properties, but is @strong{not} for
cryptographic use, and therefore not documented here. It is included
mostly because the Nettle test suite needs to generate some test data
from a small seed.

The recommended generator to use is Yarrow, described below.

@subsection Yarrow

Yarrow is a family of pseudo-randomness generators, designed for
cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson.
Yarrow-160 is described in a paper at
@url{http://www.counterpane.com/yarrow.html}, and it uses @acronym{SHA1}
and triple-DES, and has a 160-bit internal state. Nettle implements
Yarrow-256, which is similar, but uses @acronym{SHA256} and
@acronym{AES} to get an internal state of 256 bits.

Yarrow was an almost finished project, the paper mentioned above is the
closest thing to a specification for it, but some smaller details are
left out. There is no official reference implementation or test cases.
This section includes an overview of Yarrow, but for the details of
Yarrow-256, as implemented by Nettle, you have to consult the source
code. Maybe a complete specification can be written later.

Yarrow can use many sources (at least two are needed for proper
reseeding), and two randomness "pools", referred to as the "slow pool" and
the "fast pool". Input from the sources is fed alternatingly into the
two pools. When one of the sources has contributed 100 bits of entropy
to the fast pool, a "fast reseed" happens and the fast pool is mixed
into the internal state. When at least two of the sources have
contributed at least 160 bits each to the slow pool, a "slow reseed"
takes place. The contents of both pools are mixed into the internal
state. These procedures should ensure that the generator will eventually
recover after a key compromise.

The output is generated by using @acronym{AES} to encrypt a counter,
using the generator's current key. After each request for output,
another 256 bits are generated which replace the key. This ensures
forward secrecy.

Yarrow can also use a @dfn{seed file} to save state across restarts.
Yarrow is seeded by either feeding it the contents of the previous seed
file, or feeding it input from its sources until a slow reseed happens.

Nettle defines Yarrow-256 in @file{<nettle/yarrow.h>}. 

@deftp {Context struct} {struct yarrow256_ctx}
@end deftp

@deftp {Context struct} {struct yarrow_source}
Information about a single source.
@end deftp

@defvr Constant YARROW256_SEED_FILE_SIZE
The size of the Yarrow-256 seed file.
@end defvr

@deftypefun void yarrow256_init (struct yarrow256_ctx *@var{ctx}, unsigned @var{nsources}, struct yarrow_source *@var{sources})
Initializes the yarrow context, and its @var{nsources} sources.
@end deftypefun

@deftypefun void yarrow256_seed (struct yarrow256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{seed_file})
Seeds Yarrow-256 from a previous seed file. @var{length} should be at least
@code{YARROW256_SEED_FILE_SIZE}, but it can be larger.

The generator will trust you that the @var{seed_file} data really is
unguessable. After calling this function, you @emph{must} overwrite the old
seed file with the contents of @code{@var{ctx}->seed_file}. If it's
possible for several processes to read the seed file at about the same
time, access must be coordinated, for example using lock files.
@end deftypefun

@deftypefun int yarrow256_update (struct yarrow256_ctx *@var{ctx}, unsigned @var{source}, unsigned @var{entropy}, unsigned @var{length}, const uint8_t *@var{data})
Updates the generator with data from source @var{SOURCE} (an index that
must be smaller than the number of sources). @var{entropy} is your
estimated lower bound for the entropy in the data, measured in bits.
Calling update with zero @var{entropy} is always safe, no matter if the
data is random or not.

Returns 1 if a reseed happened, in which case the seed file can be
overwritten with the contents of @code{@var{ctx}->seed_file}. Otherwise,
the function returns 0.
@end deftypefun

@deftypefun void yarrow256_random (struct yarrow256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{dst})
Generates @var{length} octets of output. The generator must be seeded
before you call this function.

If you don't need forward secrecy, e.g. if you need non-secret
randomness for initialization vectors or padding, you can gain some
efficiency by buffering, calling this function for reasonably large
blocks of data, say 100-1000 octets at a time.
@end deftypefun

@deftypefun int yarrow256_is_seeded (struct yarrow256_ctx *@var{ctx})
Returns 1 if the generator is seeded and ready to generate output,
otherwise 0.
@end deftypefun

@deftypefun unsigned yarrow256_needed_sources (struct yarrow256_ctx *@var{ctx})
Returns the number of sources that must reach the threshold before a
slow reseed will happen. Useful primarily when the generator is unseeded.
@end deftypefun

@deftypefun void yarrow256_force_reseed (struct yarrow256_ctx *@var{ctx})
Causes a slow reseed to take place immediately, regardless of the
current entropy estimates of the two pools. Use with care.
@end deftypefun

Nettle includes an entropy estimator for one kind of input source: User
keyboard input.

@deftp {Context struct} {struct yarrow_key_event_ctx}
Information about recent key events.
@end deftp

@deftypefun void yarrow_key_event_init (struct yarrow_key_event_ctx *@var{ctx})
Initializes the context.
@end deftypefun

@deftypefun unsigned yarrow_key_event_estimate(struct yarrow_key_event_ctx *@var{ctx}, unsigned @var{key}, unsigned @var{time})
@var{key} is the id of the key (ASCII value, hardware key code, X
keysym, @dots{} it doesn't matter), and @var{time} is the timestamp of
the event. The time must be given in units matching the resolution by
which you read the clock. If you read the clock with microsecond
precision, @var{time} should be provided in units of microseconds. But
if you use @code{gettimeofday} on a typical Unix system where the clock
ticks 10 or so microseconds at a time, @var{time} should be given in
units of 10 microseconds.

Returns an entropy estimate, in bits, suitable for calling
@code{yarrow256_update}. Usually, 0, 1 or 2 bits.
@end deftypefun

@node Miscellaneous functions, Compatibility functions, Randomness, Reference
@comment  node-name,  next,  previous,  up
@section Miscellaneous functions

@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

@code{memxor} is declared in @file{<nettle/memxor.h>}.

@node Compatibility functions,  , Miscellaneous functions, Reference
@comment  node-name,  next,  previous,  up
@section Compatibility functions

For convenience, Nettle includes alternative interfaces to some
algorithms, for compatibility with some other popular crypto toolkits.
These are not fully documented here; refer to the source or to the
documentation for the original implementation.

MD5 is defined in [RFC 1321], which includes a reference implementation.
Nettle defines a compatible interface to MD5 in
@file{<nettle/md5-compat.h>}. This file defines the typedef
@code{MD5_CTX}, and declares the functions @code{MD5Init}, @code{MD5Update} and
@code{MD5Final}.

Eric Young's "libdes" (also part of OpenSSL) is a quite popular DES
implementation. Nettle includes a subset if it's interface in
@file{<nettle/des-compat.h>}. This file defines the typedefs
@code{des_key_schedule} and @code{des_cblock}, two constants
@code{DES_ENCRYPT} and @code{DES_DECRYPT}, and declares one global
variable @code{des_check_key}, and the functions @code{des_cbc_cksum}
@code{des_cbc_encrypt}, @code{des_ecb2_encrypt},
@code{des_ecb3_encrypt}, @code{des_ecb_encrypt},
@code{des_ede2_cbc_encrypt}, @code{des_ede3_cbc_encrypt},
@code{des_is_weak_key}, @code{des_key_sched}, @code{des_ncbc_encrypt}
@code{des_set_key}, and @code{des_set_odd_parity}.

@node Nettle soup, Installation, Reference, Top
@comment  node-name,  next,  previous,  up
@chapter Traditional Nettle Soup
For the serious nettle hacker, here is a recipe for nettle soup. 4 servings

@itemize @w{}
@item
1 liter fresh nettles (urtica dioica)
@item
2 tablespoons butter
@item
3 tablespoons flour
@item
1 liter bouillon (meat or vegetable)
@item
1/2 teaspoon salt
@item
a tad white pepper
@item
some cream or milk
@end itemize

Gather 1 liter fresh nettles. Use gloves! Small, tender shoots are
preferable but the tops of larger nettles can also be used.

@c replace "hack" with "chop"?

Rinse the nettles very well. Boil them for 10 minutes in lightly salted
water. Strain the nettles and save the water. Hack the nettles. Melt the
butter and mix in the flour. Dilute with bouillon and the nettle-water you
save earlier. Add the hacked nettles. If you wish you can add some milk
or cream at this stage. Bring to a boil and let boil for a few minutes.
Season with salt and pepper.

Serve with boiled egg-halves.

@c And the original Swedish version.
@ignore

Recept på nässelsoppa
4 portioner

1 l färska nässlor
2 msk smör
3 msk vetemjöl
1 l kött- eller grönsaksbuljong
1/2 tsk salt
1-2 krm peppar
(lite grädde eller mjölk)

Plocka 1 liter färska nässlor. Använd handskar! Helst små och späda
skott, men topparna av större nässlor går också bra.

Skölj nässlorna väl. Förväll dem ca 10 minuter i lätt saltat vatten.
Häll av och spara spadet. Hacka nässlorna. Smält smöret, rör i mjöl och
späd med buljong och nässelspad. Lägg i de hackade nässlorna. Om så
önskas, häll i en skvätt mjölk eller grädde. Koka några minuter, och
smaksätt med salt och peppar.

Servera med kokta ägghalvor.
@end ignore

@node Installation, Index, Nettle soup, 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

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

Only static libraries are installed.

@node Index,  , Installation, Top
@comment  node-name,  next,  previous,  up
@unnumbered Function and Concept Index

@printindex cp

@bye

Local Variables:
ispell-local-dictionary: "american"
ispell-skip-region-alist: (
 (ispell-words-keyword forward-line)
 ("^@example" . "^@end.*example")
 ("^@ignore" . "^@end.*ignore")
 ("^@\\(end\\|syncodeindex\\|vskip\\|\\(un\\)?macro\\|node\\|deftp\\) .*$")
 ("^@\\(printindex\\|set\\) .*$")
 ("^@def.*$")
 ;; Allows one level of nested braces in the argument 
 ("@\\(uref\\|value\\|badspell\\|code\\|file\\|var\\|url\\){[^{}]*\\({[^{}]*}[^{}]*\\)*}")
 ("@[a-z]+[{ ]")
 ("@[a-z]+$")
 ("\input texinfo.*$")
 ("ispell-ignore" . "ispell-end-ignore")
 ("^Local Variables:$" . "^End:$"))
End:

@c  LocalWords:  cryptographics crypto LSH GNUPG API GPL LGPL aes rijndael ller
@c  LocalWords:  Sevilla arcfour RC Niels Dassen Colin Kuchling Biham sha Ruud
@c  LocalWords:  Gutmann twofish de Rooij struct MB Rivest RFC Nettle's ECB CBC
@c  LocalWords:  RSA Daemen Rijnmen Schneier DES's ede structs oddnesses HMAC
@c  LocalWords:  NIST Alice's GMP bignum Diffie Adi Shamir Adleman Euclid's ASN
@c  LocalWords:  PKCS callbacks Young's urtica dioica autoconf automake SSH tad
@c  LocalWords:  unguessability reseeding reseed alternatingly keysym