hi nettle folks--

i've been reading the latest nettle docs [0], and i wanted to say that they are excellent. Clear explanations, and useful contextual help about how various crypto primitives can be used in real-world settings as well. Thanks for this!

I have two nit-picks that i'd like to share in hopes of making excellent documentation even better.

0) avoid replay attacks in pubkey authorization example.

Section 6.5 contains the following paragraph:

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

This simple scheme is actually vulnerable to a replay attack: an man-in-the-middle attacker can pose as the service to the user while simultaneously connecting to the service directly. The attacker gets a nonce from the server, passes it to the user for signing, returns the user's response to the service, and gains access.

One way to avoid this is to ensure that the "random nonce" to be signed by the user is actually a negotiated value that neither party can fully control.

I recognize that this documentation shouldn't go into deep detail here, but i've seen real-world attempts to implement cryptosystems that are subject to this kind of replay attack :(. i think it would be a good idea to warn against it somehow.

1) "bad things may happen", "a few subtle issues", etc. should have outbound links

There are several places in the docs that mention potential security concerns implementators should be aware of. For example, the remark about CBC providing "information leakage" could link to http://www.kb.cert.org/vuls/id/958563

Again, i'm not pushing for major changes or lots of intrusive commentary here (and i don't know how difficult it is to make outbound links in the documentation system used by nettle) but it would make already good docs even better.

Thanks again for this library!

Regards,

--dkg

[0] http://www.lysator.liu.se/~nisse/nettle/nettle.html#Cipher-modes