diff --git a/nettle.texinfo b/nettle.texinfo
index 7474353bf2beae287db4db3d82fdbed22d77fec1..e0d44e12fd44624f9e6e3d7d39289c90ec8c2e9a 100644
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -1332,13 +1332,21 @@ 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".
+
+@menu
+* RSA:: The RSA public key algorithm.
+* DSA:: The DSA digital signature algorithm.
+@end menu
+
+@node RSA, DSA, Public-key algorithms, Public-key algorithms
+@comment node-name, next, previous, up
@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.
+The @acronym{RSA} algorithm 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
@@ -1406,9 +1414,6 @@ computed, the operation returns true if and only if the result equals
@subsection Nettle's @acronym{RSA} support
-@c FIXME: Update for RSA renaming. and new *_digest functions. Document
-@c dsa.
-
Nettle represents @acronym{RSA} keys using two structures that contain
large numbers (of type @code{mpz_t}).
@@ -1428,16 +1433,16 @@ signing. Instead, the factors @code{p} and @code{q}, and the parameters
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})
+@deftypefun void rsa_public_key_init (struct rsa_public_key *@var{pub})
+@deftypefunx void rsa_private_key_init (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})
+@deftypefun void rsa_public_key_clear (struct rsa_public_key *@var{pub})
+@deftypefunx void rsa_private_key_clear (struct rsa_private_key *@var{key})
Calls @code{mpz_clear} on all numbers in the key struct.
@end deftypefun
@@ -1449,8 +1454,8 @@ to customize allocation, see
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})
+@deftypefun int rsa_public_key_prepare (struct rsa_public_key *@var{pub})
+@deftypefunx int rsa_private_key_prepare (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
@@ -1460,23 +1465,40 @@ than the minimum size specified by PKCS#1.
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.
+rest of the work. There are also alternative functions that take the
+@acronym{md5} or @acronym{sha1} hash digest as argument.
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})
+@deftypefun void rsa_md5_sign (const struct rsa_private_key *@var{key}, struct md5_ctx *@var{hash}, mpz_t @var{signature})
+@deftypefunx void rsa_sha1_sign (const 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})
+@deftypefun void rsa_md5_sign_digest (const struct rsa_private_key *@var{key}, const uint8_t *@var{digest}, mpz_t @var{signature})
+@deftypefunx void rsa_sha1_sign_digest (const struct rsa_private_key *@var{key}, const uint8_t *@var{digest}, mpz_t @var{signature});
+Creates a signature from the given hash digest. @var{digest} should
+point to a digest of size @code{MD5_DIGEST_SIZE} or
+@code{SHA1_DIGEST_SIZE}, respectively. The signature is stored in
+@var{signature} (which must have been @code{mpz_init}:ed earlier)
+@end deftypefun
+
+@deftypefun int rsa_md5_verify (const struct rsa_public_key *@var{key}, struct md5_ctx *@var{hash}, const mpz_t @var{signature})
+@deftypefunx int rsa_sha1_verify (const 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
+@deftypefun int rsa_md5_verify_digest (const struct rsa_public_key *@var{key}, const uint8_t *@var{digest}, const mpz_t @var{signature})
+@deftypefunx int rsa_sha1_verify_digest (const struct rsa_public_key
+*@var{key}, const uint8_t *@var{digest}, const mpz_t @var{signature})
+Returns 1 if the signature is valid, or 0 if it isn't. @var{digest} should
+point to a digest of size @code{MD5_DIGEST_SIZE} or
+@code{SHA1_DIGEST_SIZE}, respectively.
+@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
@@ -1491,8 +1513,8 @@ 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.
+don't need to call @code{rsa_public_key_prepare} or
+@code{rsa_private_key_prepare} after key generation.
@var{random_ctx} and @var{random} is a randomness generator.
@code{random(random_ctx, length, dst)} should generate @code{length}
@@ -1509,12 +1531,204 @@ 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 DSA, , RSA, Public-key algorithms
+@comment node-name, next, previous, up
+@subsection Nettle's @acronym{DSA} support
+
+The @acronym{DSA} digital signature algorithm is more complex than
+@acronym{RSA}. It was specified during the early 1990s, and in 1994 NIST
+published FIPS 186 which is the authoritative specification. Sometimes
+@acronym{DSA} is referred to using the acronym @acronym{DSS}, for
+Digital Signature Standard.
+
+For @acronym{DSA}, the underlying mathematical problem is the
+computation of discreet logarithms. The public key consists of a large
+prime @code{p}, a small prime @code{q} which is a factor of @code{p-1},
+a number @code{g} which generates a subgroup of order @code{q} modulo
+@code{p}, and an element @code{y} in that subgroup.
+
+The size of @code{q} is fixed to 160 bits, to match with the
+@acronym{SHA1} hash algorithm which is used in @acronym{DSA}. The size
+of @code{q} is in principle unlimited, but the standard specifies only
+nine specific sizes: @code{512 + l*64}, where @code{l} is between 0 and
+8. Thus, the maximum size of @code{p} is 1024 bits, at that is also the
+recommended size.
+
+The subgroup requirement means that if you compute
+
+@example
+g^t mod p
+@end example
+
+for all possible integers @code{t}, you will get precisely @code{q}
+distinct values.
+
+The private key is a secret exponent @code{x}, such that
+
+@example
+g^x = y mod p
+@end example
+
+In mathematical speak, @code{x} is the @dfn{discrete logarithm} of
+@code{y} mod @code{p}, with respect to the generator @code{d}. The size
+of @code{x} will also be about 160 bits.
+
+The signature generation algorithm is randomized; in order to create a
+@acronym{DSA} signature, you need a good source for random numbers
+(@pxref{Randomness}).
+
+To create a signature, one starts with the hash digest of the message,
+@code{h}, which is a 160 bit number, and a random number @code{k,
+0<k<q}, also 160 bits. Next, one computes
+
+@example
+r = (g^k mod p) mod q
+s = k^-1 (h + x r) mod q
+@end example
+
+The signature is the pair @code{(r, s)}, two 160 bit numbers. Note the
+two different mod operations when computing @code{r}, and the use of the
+secret exponent @code{x}.
+
+To verify a signature, one first checks that @code{0 < r,s < q}, and
+then one computes backwards,
+
+@example
+w = s^-1 mod q
+v = (g^(w h) y^(w r) mod p) mod q
+@end example
+
+The signature is valid if @code{v = r}. This works out because @code{w =
+s^-1 mod q = k (h + x r)^-1 mod q}, so that
+
+@example
+g^(w h) y^(w r) = g^(w h) (g^x)^(w r) = g^(w (h + x r)) = g^k
+@end example
+
+When reducing mod @code{q} this yields @code{r}. Note that when
+verifying a signature, we don't know either @code{k} or @code{x}: those
+numbers are secret.
+
+If you can choose between @acronym{RSA} and @acronym{DSA}, which one is
+best? Both are believed to be secure. @acronym{DSA} gained popularity
+in the late 1990s, as a patent free alternative to @acronym{RSA}. Now
+that the @acronym{RSA} patents have expired, there's no compelling
+reason to want to use @acronym{DSA}.
+
+@acronym{DSA} signatures are smaller than @acronym{RSA} signatures,
+which is important for some specialized applications.
+
+From a practical point of view, @acronym{DSA}'s need for a good
+randomness source is a serious disadvantage. If you ever use the same
+@code{k} (and @code{r}) for two different message, you leak your private
+key.
+
+@subsection Nettle's @acronym{DSA} support
+
+Like for @acronym{RSA}, Nettle represents @acronym{DSA} keys using two
+structures, containing values of type @code{mpz_t}. For information on
+how to customize allocation, see @xref{Custom Allocation,,GMP
+Allocation,gmp, GMP Manual}.
+
+Most of the @acronym{DSA} functions are very similar to the
+corresponding @acronym{RSA} functions, but there are a few differences
+pointed out below. For a start, there are no functions corresponding to
+@code{rsa_public_key_prepare} and @code{rsa_private_key_prepare}.
+
+@deftp {Context struct} {dsa_public_key} p q g y
+The public parameters described above.
+@end deftp
+
+@deftp {Context struct} {dsa_private_key} x
+The private key @code{x}.
+@end deftp
+
+Before use, these structs must be initialized by calling one of
+
+@deftypefun void dsa_public_key_init (struct dsa_public_key *@var{pub})
+@deftypefunx void dsa_private_key_init (struct dsa_private_key *@var{key})
+Calls @code{mpz_init} on all numbers in the key struct.
+@end deftypefun
+
+When finished with them, the space for the numbers must be
+deallocated by calling one of
+
+@deftypefun void dsa_public_key_clear (struct dsa_public_key *@var{pub})
+@deftypefunx void dsa_private_key_clear (struct dsa_private_key *@var{key})
+Calls @code{mpz_clear} on all numbers in the key struct.
+@end deftypefun
+
+Signatures are represented using the structure below, and need to be
+initialized and cleared in the same way as the key structs.
+
+@deftp {Context struct} {dsa_signature} r s
+@end deftp
+
+@deftypefun void dsa_signature_init (struct dsa_signature *@var{signature})
+@deftypefunx void dsa_signature_clear (struct dsa_signature *@var{signature})
+You must call @code{dsa_signature_init} before creating or using a
+signature, and call @code{dsa_signature_clear} when you are finished
+with it.
+@end deftypefun
+
+For signing, you need to provide both the public and the private key
+(unlike @acronym{RSA}, where the private key struct includes all
+information needed for signing), and a source for random numbers.
+Signatures always use the @acronym{SHA1} hash function.
+
+@deftypefun void dsa_sign (const struct dsa_public_key *@var{pub}, const struct dsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, struct sha1_ctx *@var{hash}, struct dsa_signature *@var{signature})
+@deftypefunx void dsa_sign_digest (const struct dsa_public_key *@var{pub}, const struct dsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, const uint8_t *@var{digest}, struct dsa_signature *@var{signature})
+Creates a signature from the given hash context or digest.
+@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}.
+@end deftypefun
+
+Verifying signatures is a little easier, since no randomness generator is
+needed. The functions are
+
+@deftypefun int dsa_verify (const struct dsa_public_key *@var{key}, struct sha1_ctx *@var{hash}, const struct dsa_signature *@var{signature})
+@deftypefunx int dsa_verify_digest (const struct dsa_public_key *@var{key}, const uint8_t *@var{digest}, const struct dsa_signature *@var{signature})
+Verifies a signature. Returns 1 if the signature is valid, otherwise 0.
+@end deftypefun
+
+Key generation uses mostly the same parameters as the corresponding
+@acronym{RSA} function.
+
+@deftypefun int dsa_generate_keypair (struct dsa_public_key *@var{pub}, struct dsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, void *@var{progress_ctx}, nettle_progress_func @var{progress}, unsigned @var{bits})
+@var{pub} and @var{key} is where the resulting key pair is stored. The
+structs should be initialized before you call this function.
+
+@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{bits} is the desired size of @code{p}, in bits. To generate keys
+that conform to the standard, you must use a value of the form @code{512
++ l*64}, for @code{0 <= l <= 8}. Keys smaller than 768 bits are not
+considered secure, so you should probably stick to 1024. Non-standard
+sizes are possible, in particular sizes larger than 1024 bits, although
+@acronym{DSA} implementations can not in general be expected to support
+such keys. Also note that using very large keys doesn't make much sense,
+because the security is also limited by the size of the smaller prime
+@code{q}, which is always 160 bits.
+
+Returns 1 on success, and 0 on failure. The function will fail if
+@var{bits} is too small.
+@end deftypefun
+
@node Randomness, Miscellaneous functions, Public-key algorithms, Reference
@comment node-name, next, previous, up
@section Randomness