NOTES

   1 * Design of new, multi-subnet secnet protocol
   2
   3 Like the first (1995/6) version, we're tunnelling IP packets inside
   4 UDP packets. To defeat various restrictions which may be imposed on us
   5 by network providers (like the prohibition of incoming TCP
   6 connections) we're sticking with UDP for everything this time,
   7 including key setup. This means we have to handle retries, etc.
   8
   9 Other new features include being able to deal with subnets hidden
  10 behind changing 'real' IP addresses, and the ability to choose
  11 algorithms and keys per pair of communicating sites.
  12
  13 ** Configuration and structure
  14
  15 [The original plan]
  16
  17 The network is made up from a number of 'sites'. These are collections
  18 of machines with private IP addresses. The new secnet code runs on
  19 machines which have interfaces on the private site network and some
  20 way of accessing the 'real' internet.
  21
  22 Each end of a tunnel is identified by a name. Often it will be
  23 convenient for every gateway machine to use the same name for each
  24 tunnel endpoint, but this is not vital. Individual tunnels are
  25 identified by their two endpoint names.
  26
  27 [The new plan]
  28
  29 It appears that people want to be able to use secnet on mobile
  30 machines like laptops as well as to interconnect sites. In particular,
  31 they want to be able to use their laptop in three situations:
  32
  33 1) connected to their internal LAN by a cable; no tunnel involved
  34 2) connected via wireless, using a tunnel to protect traffic
  35 3) connected to some other network, using a tunnel to access the
  36 internal LAN.
  37
  38 They want the laptop to keep the same IP address all the time.
  39
  40 Case (1) is simple.
  41
  42 Case (2) requires that the laptop run a copy of secnet, and have a
  43 tunnel configured between it and the main internal LAN default
  44 gateway. secnet must support the concept of a 'soft' tunnel where it
  45 adds a route and causes the gateway to do proxy-ARP when the tunnel is
  46 up, and removes the route again when the tunnel is down.
  47
  48 The usual prohibition of packets coming in from one tunnel and going
  49 out another must be relaxed in this case (in particular, the
  50 destination address of packets from these 'mobile station' tunnels may
  51 be another tunnel as well as the host).
  52
  53 (Quick sanity check: if chiark's secnet address was in
  54 192.168.73.0/24, would this work properly? Yes, because there will be
  55 an explicit route to it, and proxy ARP will be done for it. Do we want
  56 packets from the chiark tunnel to be able to go out along other
  57 routes? No. So, spotting a 'local' address in a remote site's list of
  58 networks isn't sufficient to switch on routing for a site. We need an
  59 explicit option. NB packets may be routed if the source OR the
  60 destination is marked as allowing routing [otherwise packets couldn't
  61 get back from eg. chiark to a laptop at greenend]).
  62
  63 ** VPN-level configuration
  64
  65 At a high level we just want to be able to indicate which groups of
  66 users can claim ownership of which ranges of IP addresses. Assuming
  67 these users (or their representatives) all have accounts on a single
  68 machine, we can automate the submission of keys and other information
  69 to make up a 'sites' file for the entire VPN.
  70
  71 The distributed 'sites' file should be in a more restricted format
  72 than the secnet configuration file, to prevent attackers who manage to
  73 distribute bogus sites files from taking over their victim's machines.
  74
  75 The distributed 'sites' file is read one line at a time. Each line
  76 consists of a keyword followed by other information. It defines a
  77 number of VPNs; within each VPN it defines a number of locations;
  78 within each location it defines a number of sites. These VPNs,
  79 locations and sites are turned into a secnet.conf file fragment using
  80 a script.
  81
  82 Some keywords are valid at any 'level' of the distributed 'sites'
  83 file, indicating defaults.
  84
  85 The keywords are:
  86
  87 vpn n: we are now declaring information to do with VPN 'n'. Must come first.
  88
  89 location n: we are now declaring information for location 'n'.
  90
  91 site n: we are now declaring information for site 'n'.
  92 endsite: we're finished declaring information for the current site
  93
  94 restrict-nets a b c ...: restrict the allowable 'networks' for the current
  95   level to those in this list.
  96 end-definitions: prevent definition of further vpns and locations, and
  97   modification of defaults at VPN level
  98
  99 dh x y: the current VPN uses the specified group; x=modulus, y=generator
 100
 101 hash x: which hash function to use. Valid options are 'md5' and 'sha1'.
 102
 103 admin n: administrator email address for current level
 104
 105 key-lifetime n
 106 setup-retries n
 107 setup-timeout n
 108 wait-time n
 109 renegotiate-time n
 110
 111 address a b: a=dnsname, b=port
 112 networks a b c ...
 113 pubkey x y z: x=keylen, y=encryption key, z=modulus
 114 mobile: declare this to be a 'mobile' site
 115
 116 ** Logging etc.
 117
 118 There are several possible ways of running secnet:
 119
 120 'reporting' only: --version, --help, etc. command line options and the
 121 --just-check-config mode.
 122
 123 'normal' run: perform setup in the foreground, and then background.
 124
 125 'failed' run: setup in the foreground, and terminate with an error
 126 before going to background.
 127
 128 'reporting' modes should never output anything except to stdout/stderr.
 129 'normal' and 'failed' runs output to stdout/stderr before
 130 backgrounding, then thereafter output only to log destinations.
 131
 132 ** Protocols
 133
 134 *** Protocol environment:
 135
 136 Each gateway machine serves a particular, well-known set of private IP
 137 addresses (i.e. the agreement over which addresses it serves is
 138 outside the scope of this discussion). Each gateway machine has an IP
 139 address on the interconnecting network (usually the Internet), which
 140 may be dynamically allocated and may change at any point.
 141
 142 Each gateway knows the RSA public keys of the other gateways with
 143 which it wishes to communicate. The mechanism by which this happens is
 144 outside the scope of this discussion. There exists a means by which
 145 each gateway can look up the probable IP address of any other.
 146
 147 *** Protocol goals:
 148
 149 The ultimate goal of the protocol is for the originating gateway
 150 machine to be able to forward packets from its section of the private
 151 network to the appropriate gateway machine for the destination
 152 machine, in such a way that it can be sure that the packets are being
 153 sent to the correct destination machine, the destination machine can
 154 be sure that the source of the packets is the originating gateway
 155 machine, and the contents of the packets cannot be understood other
 156 than by the two communicating gateways.
 157
 158 XXX not sure about the address-change stuff; leave it out of the first
 159 version of the protocol. From experience, IP addresses seem to be
 160 quite stable so the feature doesn't gain us much.
 161
 162 **** Protocol sub-goal 1: establish a shared key
 163
 164 Definitions:
 165
 166 A is the originating gateway machine
 167 B is the destination gateway machine
 168 PK_A is the public RSA key of A
 169 PK_B is the public RSA key of B
 170 PK_A^-1 is the private RSA key of A
 171 PK_B^-1 is the private RSA key of B
 172 x is the fresh private DH key of A
 173 y is the fresh private DH key of B
 174 k is g^xy mod m
 175 g and m are generator and modulus for Diffie-Hellman
 176 nA is a nonce generated by A
 177 nB is a nonce generated by B
 178 iA is an index generated by A, to be used in packets sent from B to A
 179 iB is an index generated by B, to be used in packets sent from A to B
 180 i? is appropriate index for receiver
 181
 182 Note that 'i' may be re-used from one session to the next, whereas 'n'
 183 is always fresh.
 184
 185 Messages:
 186
 187 1) A->B: *,iA,msg1,A,B,protorange-A,nA
 188
 189 2) B->A: iA,iB,msg2,B,A,chosen-protocol,nB,nA
 190
 191 (The order of B and A reverses in alternate messages so that the same
 192 code can be used to construct them...)
 193
 194 3) A->B: {iB,iA,msg3,A,B,protorange-A,chosen-protocol,nA,nB,g^x mod m}_PK_A^-1
 195
 196 If message 1 was a replay then A will not generate message 3, because
 197 it doesn't recognise nA.
 198
 199 If message 2 was from an attacker then B will not generate message 4,
 200 because it doesn't recognise nB.
 201
 202 If an attacker is trying to manipulate the chosen protocol, B can spot
 203 this when it sees A's message 3.
 204
 205 4) B->A: {iA,iB,msg4,B,A,protorange-B,chosen-protocol,nB,nA,g^y mod m}_PK_B^-1
 206
 207 At this point, A and B share a key, k. B must keep retransmitting
 208 message 4 until it receives a packet encrypted using key k.
 209
 210 A can abandon the exchange if the chosen protocol is not the one that
 211 it would have chosen knowing the acceptable protocol ranges of A and
 212 B.
 213
 214 5) A: iB,iA,msg5,(ping/msg5)_k
 215
 216 6) B: iA,iB,msg6,(pong/msg6)_k
 217
 218 (Note that these are encrypted using the same transform that's used
 219 for normal traffic, so they include sequence number, MAC, etc.)
 220
 221 The ping and pong messages can be used by either end of the tunnel at
 222 any time, but using msg0 as the unencrypted message type indicator.
 223
 224 **** Protocol sub-goal 2: end the use of a shared key
 225
 226 7) i?,i?,msg0,(end-session/msg7,A,B)_k
 227
 228 This message can be sent by either party. Once sent, k can be
 229 forgotten. Once received and checked, k can be forgotten. No need to
 230 retransmit or confirm reception. It is suggested that this message be
 231 sent when a key times out, or the tunnel is forcibly terminated for
 232 some reason.
 233
 234 XXX not yet implemented.
 235
 236 8) i?,i?,NAK/msg8
 237
 238 If the link-layer can't work out what to do with a packet (session has
 239 gone away, etc.) it can transmit a NAK back to the sender.  The sender
 240 can then try to verify whether the session is alive by sending ping
 241 packets, and forget the key if it isn't. Potential denial-of-service
 242 if the attacker can stop the ping/pong packets getting through (the
 243 key will be forgotten and another key setup must take place), but if
 244 they can delete packets then we've lost anyway...
 245
 246 The attacker can of course forge NAKs since they aren't protected. But
 247 if they can only forge packets then they won't be able to stop the
 248 ping/pong working. Trust in NAKs can be rate-limited...
 249
 250 Alternative idea (which is actually implemented): if you receive a
 251 packet you can't decode, because there's no key established, then
 252 initiate key setup...
 253
 254 Keepalives are probably a good idea.
 255
 256 **** Protocol sub-goal 3: send a packet
 257
 258 9) i?,i?,msg0,(send-packet/msg9,packet)_k