chiark / gitweb /
site, transform: Do not initiate rekey when packets too much out of order
[secnet.git] / 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 [the even newer plan]
64
65 secnet sites are configured to grant access to particular IP address
66 ranges to the holder of a particular public key.  The key can certify
67 other keys, which will then be permitted to use a subrange of the IP
68 address range of the certifying key.
69
70 This means that secnet won't know in advance (i.e. at configuration
71 time) how many tunnels it might be required to support, so we have to
72 be able to create them (and routes, and so on) on the fly.
73
74 ** VPN-level configuration
75
76 At a high level we just want to be able to indicate which groups of
77 users can claim ownership of which ranges of IP addresses. Assuming
78 these users (or their representatives) all have accounts on a single
79 machine, we can automate the submission of keys and other information
80 to make up a 'sites' file for the entire VPN.
81
82 The distributed 'sites' file should be in a more restricted format
83 than the secnet configuration file, to prevent attackers who manage to
84 distribute bogus sites files from taking over their victim's machines.
85
86 The distributed 'sites' file is read one line at a time. Each line
87 consists of a keyword followed by other information. It defines a
88 number of VPNs; within each VPN it defines a number of locations;
89 within each location it defines a number of sites. These VPNs,
90 locations and sites are turned into a secnet.conf file fragment using
91 a script.
92
93 Some keywords are valid at any 'level' of the distributed 'sites'
94 file, indicating defaults.
95
96 The keywords are:
97
98 vpn n: we are now declaring information to do with VPN 'n'. Must come first.
99
100 location n: we are now declaring information for location 'n'.
101
102 site n: we are now declaring information for site 'n'.
103 endsite: we're finished declaring information for the current site
104
105 restrict-nets a b c ...: restrict the allowable 'networks' for the current
106   level to those in this list.
107 end-definitions: prevent definition of further vpns and locations, and
108   modification of defaults at VPN level
109
110 dh x y: the current VPN uses the specified group; x=modulus, y=generator
111
112 hash x: which hash function to use. Valid options are 'md5' and 'sha1'.
113
114 admin n: administrator email address for current level
115
116 key-lifetime n
117 setup-retries n
118 setup-timeout n
119 wait-time n
120 renegotiate-time n
121
122 address a b: a=dnsname, b=port
123 networks a b c ...
124 pubkey x y z: x=keylen, y=encryption key, z=modulus
125 mobile: declare this to be a 'mobile' site
126
127 ** Logging etc.
128
129 There are several possible ways of running secnet:
130
131 'reporting' only: --version, --help, etc. command line options and the
132 --just-check-config mode.
133
134 'normal' run: perform setup in the foreground, and then background.
135
136 'failed' run: setup in the foreground, and terminate with an error
137 before going to background.
138
139 'reporting' modes should never output anything except to stdout/stderr.
140 'normal' and 'failed' runs output to stdout/stderr before
141 backgrounding, then thereafter output only to log destinations.
142
143 ** Protocols
144
145 *** Protocol environment:
146
147 Each gateway machine serves a particular, well-known set of private IP
148 addresses (i.e. the agreement over which addresses it serves is
149 outside the scope of this discussion). Each gateway machine has an IP
150 address on the interconnecting network (usually the Internet), which
151 may be dynamically allocated and may change at any point.
152
153 Each gateway knows the RSA public keys of the other gateways with
154 which it wishes to communicate. The mechanism by which this happens is
155 outside the scope of this discussion. There exists a means by which
156 each gateway can look up the probable IP address of any other.
157
158 *** Protocol goals:
159
160 The ultimate goal of the protocol is for the originating gateway
161 machine to be able to forward packets from its section of the private
162 network to the appropriate gateway machine for the destination
163 machine, in such a way that it can be sure that the packets are being
164 sent to the correct destination machine, the destination machine can
165 be sure that the source of the packets is the originating gateway
166 machine, and the contents of the packets cannot be understood other
167 than by the two communicating gateways.
168
169 XXX not sure about the address-change stuff; leave it out of the first
170 version of the protocol. From experience, IP addresses seem to be
171 quite stable so the feature doesn't gain us much.
172
173 **** Protocol sub-goal 1: establish a shared key
174
175 Definitions:
176
177 A is the originating gateway machine
178 B is the destination gateway machine
179 PK_A is the public RSA key of A
180 PK_B is the public RSA key of B
181 PK_A^-1 is the private RSA key of A
182 PK_B^-1 is the private RSA key of B
183 x is the fresh private DH key of A
184 y is the fresh private DH key of B
185 k is g^xy mod m
186 g and m are generator and modulus for Diffie-Hellman
187 nA is a nonce generated by A
188 nB is a nonce generated by B
189 iA is an index generated by A, to be used in packets sent from B to A
190 iB is an index generated by B, to be used in packets sent from A to B
191 i? is appropriate index for receiver
192
193 Note that 'i' may be re-used from one session to the next, whereas 'n'
194 is always fresh.
195
196 The protocol version selection stuff is not yet implemented: I'm not
197 yet convinced it's a good idea.  Instead, the initiator could try
198 using its preferred protocol (which starts with a different magic
199 number) and fall back if there's no reply.
200
201 Messages:
202
203 1) A->B: *,iA,msg1,A,B,protorange-A,nA
204
205 2) B->A: iA,iB,msg2,B,A,chosen-protocol,nB,nA
206
207 (The order of B and A reverses in alternate messages so that the same
208 code can be used to construct them...)
209
210 3) A->B: {iB,iA,msg3,A,B,protorange-A,chosen-protocol,nA,nB,g^x mod m}_PK_A^-1
211
212 If message 1 was a replay then A will not generate message 3, because
213 it doesn't recognise nA.
214
215 If message 2 was from an attacker then B will not generate message 4,
216 because it doesn't recognise nB.
217
218 If an attacker is trying to manipulate the chosen protocol, B can spot
219 this when it sees A's message 3.
220
221 4) B->A: {iA,iB,msg4,B,A,protorange-B,chosen-protocol,nB,nA,g^y mod m}_PK_B^-1
222
223 At this point, A and B share a key, k. B must keep retransmitting
224 message 4 until it receives a packet encrypted using key k.
225
226 A can abandon the exchange if the chosen protocol is not the one that
227 it would have chosen knowing the acceptable protocol ranges of A and
228 B.
229
230 5) A: iB,iA,msg5,(ping/msg5)_k
231
232 6) B: iA,iB,msg6,(pong/msg6)_k
233
234 (Note that these are encrypted using the same transform that's used
235 for normal traffic, so they include sequence number, MAC, etc.)
236
237 The ping and pong messages can be used by either end of the tunnel at
238 any time, but using msg0 as the unencrypted message type indicator.
239
240 **** Protocol sub-goal 2: end the use of a shared key
241
242 7) i?,i?,msg0,(end-session/msg7,A,B)_k
243
244 This message can be sent by either party. Once sent, k can be
245 forgotten. Once received and checked, k can be forgotten. No need to
246 retransmit or confirm reception. It is suggested that this message be
247 sent when a key times out, or the tunnel is forcibly terminated for
248 some reason.
249
250 8) i?,i?,NAK (encoded as zero)
251
252 If the link-layer can't work out what to do with a packet (session has
253 gone away, etc.) it can transmit a NAK back to the sender.  The sender
254 can then try to verify whether the session is alive by sending ping
255 packets, and forget the key if it isn't. Potential denial-of-service
256 if the attacker can stop the ping/pong packets getting through (the
257 key will be forgotten and another key setup must take place), but if
258 they can delete packets then we've lost anyway...
259
260 The attacker can of course forge NAKs since they aren't protected. But
261 if they can only forge packets then they won't be able to stop the
262 ping/pong working. Trust in NAKs can be rate-limited...
263
264 Alternative idea (which is actually implemented): if you receive a
265 packet you can't decode, because there's no key established, then
266 initiate key setup...
267
268 Keepalives are probably a good idea.
269
270 **** Protocol sub-goal 3: send a packet
271
272 9) i?,i?,msg0,(send-packet/msg9,packet)_k
273
274 Some messages may take a long time to prepare (software modexp on slow
275 machines); this is a "please wait" message to indicate that a message
276 is in preparation.
277
278 10) i?,i?,msg8,A,B,nA,nB,msg?