logging: site: Log state on PHASE_RUN entry instead of initially

[secnet.git] / NOTES

diff --git a/NOTES b/NOTES
index 6a245ec3bc3bb458ab1df49473b59cac1cd6d4d8..001c118e96f9401592560ea3332583b653ac2c55 100644 (file)
--- a/NOTES
+++ b/NOTES
@@ -140,6 +140,75 @@ before going to background.
 'normal' and 'failed' runs output to stdout/stderr before
 backgrounding, then thereafter output only to log destinations.
 
 'normal' and 'failed' runs output to stdout/stderr before
 backgrounding, then thereafter output only to log destinations.
 

+** Site long-term keys
+
+We use authenticated DH.  Sites identify themselves to each other
+using long-term signing keys.
+
+These signing keys may be for a variety of algorithms.  (An algorithm
+specifies completely how to do a signature and verification.)
+
+Each site may have several keys.  This helps support key rollover and
+algorithm agility.  Several keys of different algorithms can form a
+key group.  Usually a key group consists of keys generated at the same
+time.  A key is identified by a 4-byte group id (invented by its
+publisher and opaque) plus a 1-byte algorithm id (defined by the
+protocol spec for each algorithm).
+
+Keys are published in key sets.  A key set is a collection of key
+groups (including older keys as well as newer ones) published at a
+particular time.  Key sets have their own 4-byte ids; these are
+invented by the publisher but are ordered using sequence number
+arithmetic.  This allows reliers to favour new sets over old ones.
+
+Within each key set, some groups may be marked as `fallback'.  This
+means a group that should be tolerated by a relier only if the relier
+doesn't support any non-fallback keys.
+
+Keys within groups, and groups within sets, are ordered (by the
+publisher of the set), from most to least preferred.
+
+When deciding which public keys to accept, a relier should:
+  Process each group within the key set.
+    Discard unknown algorithms.
+    Choose a preferred algorithm:
+      Earliest in the group
+      (or local config could have algorithm prefererence).
+  Discard empty groups.
+  Discard unneeded fallback groups:
+    If any (non-empty) non-fallback groups found, discard all
+    fallback groups.  Otherwise there are only fallback groups;
+    discard all but first group in the set.
+  Discard any keys exceeding limit on number of keys honoured:
+    Limit is at least 4
+    Discard keys later in the set
+  In wire protocol, offer the resulting subset of keyids to
+  the peer and a allow the signer to select which key to use
+  from that subset.
+
+In configuration and key management, long-term private and public keys
+are octet strings.  Private keys are generally stored in disk files,
+one key per file.  The octet string for a private key should identify
+the algorithm so that passing the private key to the code for the 
+wrong algorithm does not produce results which would leak or weaken
+the key.  The octet string for a public key need not identify the
+algorithm; when it's loaded the algorithm will be known from context.
+
+The group id 00000000 is special.  It should contain only one key,
+algorithm 00.  Key 0000000000 refers to the rsa1 key promulgated
+before the key rollover/advertisement protocols, or the key which
+should be used by sites running old software.
+
+The key set id 00000000 is special and is considered older than all
+othere key sets (ie this is an exception to the sequence number
+arithmetic).  It is the implied key set id of the rsa1 key
+promulgated before the key rollover/advertisement protocols.
+
+The algorithm 00 is special and refers to the old rsa1 signature
+protocol but unusually does not identify the hash function.  The hash
+function is conventional and must be specified out of band.  In known
+existing installations it is SHA-1.
+

 ** Protocols
 
 *** Protocol environment:
 ** Protocols
 
 *** Protocol environment:


@@ -174,8 +243,9 @@ quite stable so the feature doesn't gain us much.
 
 Definitions:
 
 
 Definitions:
 

-A is the originating gateway machine
-B is the destination gateway machine
+A is the originating gateway machine name
+B is the destination gateway machine name
+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
 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


@@ -193,21 +263,101 @@ i? is appropriate index for receiver
 Note that 'i' may be re-used from one session to the next, whereas 'n'
 is always fresh.
 
 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: I'm not
-yet convinced it's a good idea.  Instead, the initiator could try
-using its preferred protocol (which starts with a different magic
-number) and fall back if there's no reply.
+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.
+ * In MSG3/MSG4: a 16-bit integer being the sender's MTU, or zero.
+   (In other messages: nothing.)  See below.
+ * In MSG2/MSG3: a list of the peer's public keys that the sender will
+   accept: (i) a 1-byte integer count (ii) that many 5-byte key ids.
+   If not present, implicitly only the special key id 0000000000.
+ * In MSG3/MSG4: an 8-bit integer being an index into the
+   receiver's public key acceptance list, with which the message
+   is signed.  If not present, implicitly the key id 00000000000.
+ * 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.
+
+2. Late capability flags may be advertised only in MSG2 or MSG3, as
+   applicable.  They are only in MSG1 with newer secnets; older
+   versions omit them.  MSG4 must advertise the same set as MSG2.
+
+Currently, the low 16 bits are allocated for negotiating bulk-crypto
+transforms.  Bits 8 to 15 are used by Secnet as default capability
+numbers for the various kinds of transform closures: bit 8 is for the
+original CBCMAC-based transform, and bit 9 for the new EAX transform;
+bits 10 to 15 are reserved for future expansion.  The the low eight bits
+are reserved for local use, e.g., to allow migration from one set of
+parameters for a particular transform to a different, incompatible set
+of parameters for the same transform.  Bit 31, if advertised by both
+ends, indicates that a mobile end gets priority in case of crossed MSG1.
+The remaining bits have not yet been assigned a purpose.
+
+Whether a capability number is early depends on its meaning, rather than
+being a static property of its number.  That said, the mobile-end-gets
+priority bit (31) is always sent as an `early' capability bit.
+
+
+MTU handling
+
+In older versions of secnet, secnet was not capable of fragmentation
+or sending ICMP Frag Needed.  Administrators were expected to configure
+consistent MTUs across the network.
+
+It is still the case in the current version that the MTUs need to be
+configured reasonably coherently across the network: the allocated
+buffer sizes must be sufficient to cope with packets from all other
+peers.
+
+However, provided the buffers are sufficient, all packets will be
+processed properly: a secnet receiving a packet larger than the
+applicable MTU for its delivery will either fragment it, or reject it
+with ICMP Frag Needed.
+
+The MTU additional data field allows secnet to advertise an MTU to the
+peer.  This allows the sending end to handle overlarge packets, before
+they are transmitted across the underlying public network.  This can
+therefore be used to work around underlying network braindamage
+affecting large packets.
+
+If the MTU additional data field is zero or not present, then the peer
+should use locally-configured MTU information (normally, its local
+netlink MTU) instead.
+
+If it is nonzero, the peer may send packets up to the advertised size
+(and if that size is bigger than the peer's administratively
+configured size, the advertiser promises that its buffers can handle
+such a large packet).
+
+A secnet instance should not assume that just because it has
+advertised an mtu which is lower than usual for the vpn, the peer will
+honour it, unless the administrator knows that the peers are
+sufficiently modern to understand the mtu advertisement option.  So
+secnet will still accept packets which exceed the link MTU (whether
+negotiated or assumed).
+

 
 Messages:
 
 
 Messages:
 

-1) A->B: *,iA,msg1,A,B,protorange-A,nA
+1) A->B: i*,iA,msg1,A+,B+,nA

 
 

-2) B->A: iA,iB,msg2,B,A,chosen-protocol,nB,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...)
 
 
 (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,protorange-A,chosen-protocol,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.
 
 If message 1 was a replay then A will not generate message 3, because
 it doesn't recognise nA.


@@ -215,18 +365,11 @@ it doesn't recognise nA.
 If message 2 was from an attacker then B will not generate message 4,
 because it doesn't recognise nB.
 
 If message 2 was from an attacker then B will not generate message 4,
 because it doesn't recognise nB.
 

-If an attacker is trying to manipulate the chosen protocol, B can spot
-this when it sees A's message 3.
-
-4) B->A: {iA,iB,msg4,B,A,protorange-B,chosen-protocol,nB,nA,g^y mod m}_PK_B^-1
+4) B->A: {iA,iB,msg4,B+,A+,nB,nA,g^y mod m}_PK_B^-1

 
 At this point, A and B share a key, k. B must keep retransmitting
 message 4 until it receives a packet encrypted using key k.
 
 
 At this point, A and B share a key, k. B must keep retransmitting
 message 4 until it receives a packet encrypted using key k.
 

-A can abandon the exchange if the chosen protocol is not the one that
-it would have chosen knowing the acceptable protocol ranges of A and
-B.
-

 5) A: iB,iA,msg5,(ping/msg5)_k
 
 6) B: iA,iB,msg6,(pong/msg6)_k
 5) A: iB,iA,msg5,(ping/msg5)_k
 
 6) B: iA,iB,msg6,(pong/msg6)_k


@@ -251,10 +394,6 @@ some reason.
 
 8) i?,i?,msg0,(send-packet/msg9,packet)_k
 
 
 8) i?,i?,msg0,(send-packet/msg9,packet)_k
 

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

 **** Other messages
 
 9) i?,i?,NAK (NAK is encoded as zero)
 **** Other messages
 
 9) i?,i?,NAK (NAK is encoded as zero)


@@ -277,3 +416,37 @@ 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.
 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.