A is the originating gateway machine name
B is the destination gateway machine name
-A+ and B+ are the names with optional additional data, currently ignored
+A+ and B+ are the names with optional additional data, see below
PK_A is the public RSA key of A
PK_B is the public RSA key of B
PK_A^-1 is the private RSA key of A
Note that 'i' may be re-used from one session to the next, whereas 'n'
is always fresh.
-The protocol version selection stuff is not yet implemented.
+The optional additional data after the sender's name consists of some
+initial subset of the following list of items:
+ * A 32-bit integer with a set of capability flags, representing the
+ abilities of the sender.
+ * More data which is yet to be defined and which must be ignored
+ by receivers.
+The optional additional data after the receiver's name is not
+currently used. If any is seen, it must be ignored.
+
+Capability flag bits must be in one the following two categories:
+
+1. Early capability flags must be advertised in MSG1 or MSG2, as
+ applicable. If MSG3 or MSG4 advertise any "early" capability bits,
+ MSG1 or MSG3 (as applicable) must have advertised them too. Sadly,
+ advertising an early capability flag will produce MSG1s which are
+ not understood by versions of secnet which predate the capability
+ mechanism.
+
+2. Late capability flags are advertised in MSG2 or MSG3, as
+ applicable. They may also appear in MSG1, but this is not
+ guaranteed. MSG4 must advertise the same set as MSG2.
+
+No capability flags are currently defined. Unknown capability flags
+should be treated as late ones.
+
Messages:
-1) A->B: *,iA,msg1,A,B,nA
+1) A->B: *,iA,msg1,A+,B+,nA
+
+i* must be encoded as 0. (However, it is permitted for a site to use
+zero as its "index" for another site.)
2) B->A: iA,iB,msg2,B+,A+,nB,nA
(The order of B and A reverses in alternate messages so that the same
code can be used to construct them...)
-3) A->B: {iB,iA,msg3,A+,B+,nA,nB,g^x mod m}_PK_A^-1
+3) A->B: {iB,iA,msg3,A+,B+,[chosen-transform],nA,nB,g^x mod m}_PK_A^-1
If message 1 was a replay then A will not generate message 3, because
it doesn't recognise nA.
the git history of it ever being sent.)
This message number is reserved.
+
+11) *,*,PROD,A,B
+
+Sent in response to a NAK from B to A. Requests that B initiates a
+key exchange with A, if B is willing and lacks a transport key for A.
+(If B doesn't have A's address configured, implicitly supplies A's
+public address.)
+
+This is necessary because if one end of a link (B) is restarted while
+a key exchange is in progress, the following bad state can persist:
+the non-restarted end (A) thinks that the key is still valid and keeps
+sending packets, but B either doesn't realise that a key exchange with
+A is necessary or (if A is a mobile site) doesn't know A's public IP
+address.
+
+Normally in these circumstances B would send NAKs to A, causing A to
+initiate a key exchange. However if A and B were already in the
+middle of a key exchange then A will not want to try another one until
+the first one has timed out ("setup-time" x "setup-retries") and then
+the key exchange retry timeout ("wait-time") has elapsed.
+
+However if B's setup has timed out, B would be willing to participate
+in a key exchange initiated by A, if A could be induced to do so.
+This is the purpose of the PROD packet.
+
+We send no more PRODs than we would want to send data packets, to
+avoid a traffic amplification attack. We also send them only in state
+WAIT, as in other states we wouldn't respond favourably. And we only
+honour them if we don't already have a key.
+
+With PROD, the period of broken communication due to a key exchange
+interrupted by a restart is limited to the key exchange total
+retransmission timeout, rather than also including the key exchange
+retry timeout.