[PATCH 05/25] NOTES: Improve documentation of NAKs.

[Ian Jackson]

Improve the description of the function of NAK packets.

Document an ancient form of NAK, MSG8.

Add a missing heading "Other messages" and put the description of the
NAK message and of the obsolete NAK in it.

Signed-off-by: Ian Jackson <ijackson at chiark.greenend.org.uk>
---
 NOTES |   41 +++++++++++++++++++++--------------------
 1 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/NOTES b/NOTES
index 84453df..6a245ec 100644
--- a/NOTES
+++ b/NOTES
@@ -247,32 +247,33 @@ retransmit or confirm reception. It is suggested that this message be
 sent when a key times out, or the tunnel is forcibly terminated for
 some reason.
 
-8) i?,i?,NAK (encoded as zero)
+**** Protocol sub-goal 3: send a packet
 
-If the link-layer can't work out what to do with a packet (session has
-gone away, etc.) it can transmit a NAK back to the sender.  The sender
-can then try to verify whether the session is alive by sending ping
-packets, and forget the key if it isn't. Potential denial-of-service
-if the attacker can stop the ping/pong packets getting through (the
-key will be forgotten and another key setup must take place), but if
-they can delete packets then we've lost anyway...
+8) i?,i?,msg0,(send-packet/msg9,packet)_k
 
-The attacker can of course forge NAKs since they aren't protected. But
-if they can only forge packets then they won't be able to stop the
-ping/pong working. Trust in NAKs can be rate-limited...
+Some messages may take a long time to prepare (software modexp on slow
+machines); this is a "please wait" message to indicate that a message
+is in preparation.
 
-Alternative idea (which is actually implemented): if you receive a
-packet you can't decode, because there's no key established, then
-initiate key setup...
+**** Other messages
 
-Keepalives are probably a good idea.
+9) i?,i?,NAK (NAK is encoded as zero)
 
-**** Protocol sub-goal 3: send a packet
+If the link-layer can't work out what to do with a packet (session has
+gone away, etc.) it can transmit a NAK back to the sender.
 
-9) i?,i?,msg0,(send-packet/msg9,packet)_k
+This can alert the sender to the situation where the sender has a key
+but the receiver doesn't (eg because it has been restarted).  The
+sender, on receiving the NAK, will try to initiate a key exchange.
 
-Some messages may take a long time to prepare (software modexp on slow
-machines); this is a "please wait" message to indicate that a message
-is in preparation.
+Forged (or overly delayed) NAKs can cause wasted resources due to
+spurious key exchange initiation, but there is a limit on this because
+of the key exchange retry timeout.
 
 10) i?,i?,msg8,A,B,nA,nB,msg?
+
+This is an obsolete form of NAK packet which is not sent by any even
+vaguely recent version of secnet.  (In fact, there is no evidence in
+the git history of it ever being sent.)
+
+This message number is reserved.
-- 
1.7.2.5