chiark / gitweb /
make-secnet-sites: Support `pkg' and `pkgf'
[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 ** Site long-term keys
144
145 We use authenticated DH.  Sites identify themselves to each other
146 using long-term signing keys.
147
148 These signing keys may be for a variety of algorithms.  (An algorithm
149 specifies completely how to do a signature and verification.)
150
151 Each site may have several keys.  This helps support key rollover and
152 algorithm agility.  Several keys of different algorithms can form a
153 key group.  Usually a key group consists of keys generated at the same
154 time.  A key is identified by a 4-byte group id (invented by its
155 publisher and opaque) plus a 1-byte algorithm id (defined by the
156 protocol spec for each algorithm).
157
158 Keys are published in key sets.  A key set is a collection of key
159 groups (including older keys as well as newer ones) published at a
160 particular time.  Key sets have their own 4-byte ids; these are
161 invented by the publisher but are ordered using sequence number
162 arithmetic.  This allows reliers to favour new sets over old ones.
163
164 Within each key set, some groups may be marked as `fallback'.  This
165 means a group that should be tolerated by a relier only if the relier
166 doesn't support any non-fallback keys.
167
168 Keys within groups, and groups within sets, are ordered (by the
169 publisher of the set), from most to least preferred.
170
171 When deciding which public keys to accept, a relier should:
172   Process each group within the key set.
173     Discard unknown algorithms.
174     Choose a preferred algorithm:
175       Earliest in the group
176       (or local config could have algorithm prefererence).
177   Discard empty groups.
178   Discard unneeded fallback groups:
179     If any (non-empty) non-fallback groups found, discard all
180     fallback groups.  Otherwise there are only fallback groups;
181     discard all but first group in the set.
182   Discard any keys exceeding limit on number of keys honoured:
183     Limit is at least 4
184     Discard keys later in the set
185   In wire protocol, offer the resulting subset of keyids to
186   the peer and a allow the signer to select which key to use
187   from that subset.
188
189 In configuration and key management, long-term private and public keys
190 are octet strings.  Private keys are generally stored in disk files,
191 one key per file.  The octet string for a private key should identify
192 the algorithm so that passing the private key to the code for the 
193 wrong algorithm does not produce results which would leak or weaken
194 the key.  The octet string for a public key need not identify the
195 algorithm; when it's loaded the algorithm will be known from context.
196
197 The group id 00000000 is special.  It should contain only one key,
198 algorithm 00.  Key 0000000000 refers to the rsa1 key promulgated
199 before the key rollover/advertisement protocols, or the key which
200 should be used by sites running old software.
201
202 The key set id 00000000 is special and is considered older than all
203 othere key sets (ie this is an exception to the sequence number
204 arithmetic).  It is the implied key set id of the rsa1 key
205 promulgated before the key rollover/advertisement protocols.
206
207 The algorithm 00 is special and refers to the old rsa1 signature
208 protocol but unusually does not identify the hash function.  The hash
209 function is conventional and must be specified out of band.  In known
210 existing installations it is SHA-1.
211
212 ** Protocols
213
214 *** Protocol environment:
215
216 Each gateway machine serves a particular, well-known set of private IP
217 addresses (i.e. the agreement over which addresses it serves is
218 outside the scope of this discussion). Each gateway machine has an IP
219 address on the interconnecting network (usually the Internet), which
220 may be dynamically allocated and may change at any point.
221
222 Each gateway knows the RSA public keys of the other gateways with
223 which it wishes to communicate. The mechanism by which this happens is
224 outside the scope of this discussion. There exists a means by which
225 each gateway can look up the probable IP address of any other.
226
227 *** Protocol goals:
228
229 The ultimate goal of the protocol is for the originating gateway
230 machine to be able to forward packets from its section of the private
231 network to the appropriate gateway machine for the destination
232 machine, in such a way that it can be sure that the packets are being
233 sent to the correct destination machine, the destination machine can
234 be sure that the source of the packets is the originating gateway
235 machine, and the contents of the packets cannot be understood other
236 than by the two communicating gateways.
237
238 XXX not sure about the address-change stuff; leave it out of the first
239 version of the protocol. From experience, IP addresses seem to be
240 quite stable so the feature doesn't gain us much.
241
242 **** Protocol sub-goal 1: establish a shared key
243
244 Definitions:
245
246 A is the originating gateway machine name
247 B is the destination gateway machine name
248 A+ and B+ are the names with optional additional data, see below
249 PK_A is the public RSA key of A
250 PK_B is the public RSA key of B
251 PK_A^-1 is the private RSA key of A
252 PK_B^-1 is the private RSA key of B
253 x is the fresh private DH key of A
254 y is the fresh private DH key of B
255 k is g^xy mod m
256 g and m are generator and modulus for Diffie-Hellman
257 nA is a nonce generated by A
258 nB is a nonce generated by B
259 iA is an index generated by A, to be used in packets sent from B to A
260 iB is an index generated by B, to be used in packets sent from A to B
261 i? is appropriate index for receiver
262
263 Note that 'i' may be re-used from one session to the next, whereas 'n'
264 is always fresh.
265
266 The optional additional data after the sender's name consists of some
267 initial subset of the following list of items:
268  * A 32-bit integer with a set of capability flags, representing the
269    abilities of the sender.
270  * In MSG3/MSG4: a 16-bit integer being the sender's MTU, or zero.
271    (In other messages: nothing.)  See below.
272  * In MSG2/MSG3: a list of the peer's public keys that the sender will
273    accept: (i) a 1-byte integer count (ii) that many 5-byte key ids.
274    If not present, implicitly only the special key id 0000000000.
275  * In MSG3/MSG4: an 8-bit integer being an index into the
276    receiver's public key acceptance list, with which the message
277    is signed.  If not present, implicitly the key id 00000000000.
278  * More data which is yet to be defined and which must be ignored
279    by receivers.
280 The optional additional data after the receiver's name is not
281 currently used.  If any is seen, it must be ignored.
282
283 Capability flag bits must be in one the following two categories:
284
285 1. Early capability flags must be advertised in MSG1 or MSG2, as
286    applicable.  If MSG3 or MSG4 advertise any "early" capability bits,
287    MSG1 or MSG3 (as applicable) must have advertised them too.  Sadly,
288    advertising an early capability flag will produce MSG1s which are
289    not understood by versions of secnet which predate the capability
290    mechanism.
291
292 2. Late capability flags are advertised in MSG2 or MSG3, as
293    applicable.  They may also appear in MSG1, but this is not
294    guaranteed.  MSG4 must advertise the same set as MSG2.
295
296 Currently, the low 16 bits are allocated for negotiating bulk-crypto
297 transforms.  Bits 8 to 15 are used by Secnet as default capability
298 numbers for the various kinds of transform closures: bit 8 is for the
299 original CBCMAC-based transform, and bit 9 for the new EAX transform;
300 bits 10 to 15 are reserved for future expansion.  The the low eight bits
301 are reserved for local use, e.g., to allow migration from one set of
302 parameters for a particular transform to a different, incompatible set
303 of parameters for the same transform.  Bit 31, if advertised by both
304 ends, indicates that a mobile end gets priority in case of crossed MSG1.
305 The remaining bits have not yet been assigned a purpose.
306
307 Whether a capability number is early depends on its meaning, rather than
308 being a static property of its number.  That said, the mobile-end-gets
309 priority bit (31) is always sent as an `early' capability bit.
310
311
312 MTU handling
313
314 In older versions of secnet, secnet was not capable of fragmentation
315 or sending ICMP Frag Needed.  Administrators were expected to configure
316 consistent MTUs across the network.
317
318 It is still the case in the current version that the MTUs need to be
319 configured reasonably coherently across the network: the allocated
320 buffer sizes must be sufficient to cope with packets from all other
321 peers.
322
323 However, provided the buffers are sufficient, all packets will be
324 processed properly: a secnet receiving a packet larger than the
325 applicable MTU for its delivery will either fragment it, or reject it
326 with ICMP Frag Needed.
327
328 The MTU additional data field allows secnet to advertise an MTU to the
329 peer.  This allows the sending end to handle overlarge packets, before
330 they are transmitted across the underlying public network.  This can
331 therefore be used to work around underlying network braindamage
332 affecting large packets.
333
334 If the MTU additional data field is zero or not present, then the peer
335 should use locally-configured MTU information (normally, its local
336 netlink MTU) instead.
337
338 If it is nonzero, the peer may send packets up to the advertised size
339 (and if that size is bigger than the peer's administratively
340 configured size, the advertiser promises that its buffers can handle
341 such a large packet).
342
343 A secnet instance should not assume that just because it has
344 advertised an mtu which is lower than usual for the vpn, the peer will
345 honour it, unless the administrator knows that the peers are
346 sufficiently modern to understand the mtu advertisement option.  So
347 secnet will still accept packets which exceed the link MTU (whether
348 negotiated or assumed).
349
350
351 Messages:
352
353 1) A->B: i*,iA,msg1,A+,B+,nA
354
355 i* must be encoded as 0.  (However, it is permitted for a site to use
356 zero as its "index" for another site.)
357
358 2) B->A: iA,iB,msg2,B+,A+,nB,nA
359
360 (The order of B and A reverses in alternate messages so that the same
361 code can be used to construct them...)
362
363 3) A->B: {iB,iA,msg3,A+,B+,[chosen-transform],nA,nB,g^x mod m}_PK_A^-1
364
365 If message 1 was a replay then A will not generate message 3, because
366 it doesn't recognise nA.
367
368 If message 2 was from an attacker then B will not generate message 4,
369 because it doesn't recognise nB.
370
371 4) B->A: {iA,iB,msg4,B+,A+,nB,nA,g^y mod m}_PK_B^-1
372
373 At this point, A and B share a key, k. B must keep retransmitting
374 message 4 until it receives a packet encrypted using key k.
375
376 5) A: iB,iA,msg5,(ping/msg5)_k
377
378 6) B: iA,iB,msg6,(pong/msg6)_k
379
380 (Note that these are encrypted using the same transform that's used
381 for normal traffic, so they include sequence number, MAC, etc.)
382
383 The ping and pong messages can be used by either end of the tunnel at
384 any time, but using msg0 as the unencrypted message type indicator.
385
386 **** Protocol sub-goal 2: end the use of a shared key
387
388 7) i?,i?,msg0,(end-session/msg7,A,B)_k
389
390 This message can be sent by either party. Once sent, k can be
391 forgotten. Once received and checked, k can be forgotten. No need to
392 retransmit or confirm reception. It is suggested that this message be
393 sent when a key times out, or the tunnel is forcibly terminated for
394 some reason.
395
396 **** Protocol sub-goal 3: send a packet
397
398 8) i?,i?,msg0,(send-packet/msg9,packet)_k
399
400 **** Other messages
401
402 9) i?,i?,NAK (NAK is encoded as zero)
403
404 If the link-layer can't work out what to do with a packet (session has
405 gone away, etc.) it can transmit a NAK back to the sender.
406
407 This can alert the sender to the situation where the sender has a key
408 but the receiver doesn't (eg because it has been restarted).  The
409 sender, on receiving the NAK, will try to initiate a key exchange.
410
411 Forged (or overly delayed) NAKs can cause wasted resources due to
412 spurious key exchange initiation, but there is a limit on this because
413 of the key exchange retry timeout.
414
415 10) i?,i?,msg8,A,B,nA,nB,msg?
416
417 This is an obsolete form of NAK packet which is not sent by any even
418 vaguely recent version of secnet.  (In fact, there is no evidence in
419 the git history of it ever being sent.)
420
421 This message number is reserved.
422
423 11) *,*,PROD,A,B
424
425 Sent in response to a NAK from B to A.  Requests that B initiates a
426 key exchange with A, if B is willing and lacks a transport key for A.
427 (If B doesn't have A's address configured, implicitly supplies A's
428 public address.)
429
430 This is necessary because if one end of a link (B) is restarted while
431 a key exchange is in progress, the following bad state can persist:
432 the non-restarted end (A) thinks that the key is still valid and keeps
433 sending packets, but B either doesn't realise that a key exchange with
434 A is necessary or (if A is a mobile site) doesn't know A's public IP
435 address.
436
437 Normally in these circumstances B would send NAKs to A, causing A to
438 initiate a key exchange.  However if A and B were already in the
439 middle of a key exchange then A will not want to try another one until
440 the first one has timed out ("setup-time" x "setup-retries") and then
441 the key exchange retry timeout ("wait-time") has elapsed.
442
443 However if B's setup has timed out, B would be willing to participate
444 in a key exchange initiated by A, if A could be induced to do so.
445 This is the purpose of the PROD packet.
446
447 We send no more PRODs than we would want to send data packets, to
448 avoid a traffic amplification attack.  We also send them only in state
449 WAIT, as in other states we wouldn't respond favourably.  And we only
450 honour them if we don't already have a key.
451
452 With PROD, the period of broken communication due to a key exchange
453 interrupted by a restart is limited to the key exchange total
454 retransmission timeout, rather than also including the key exchange
455 retry timeout.