1 Routing and Erouting in Pluto
2 =============================
4 RCSID $Id: routing.txt,v 1.4 2001/06/08 00:21:01 dhr Exp $
6 This is meant as internal documentation for Pluto. As such, it
7 presumes some understanding of Pluto's code.
9 It also describes KLIPS 1 erouting, including details not otherwise
10 documented. KLIPS 1 documentation would be better included in KLIPS.
12 Routing and erouting are complicated enough that the Pluto code needs
13 a guide. This document is meant to be that guide.
16 Mechanisms available to Pluto
17 -----------------------------
19 All outbound packets that are to be processed by KLIPS 1 must be
20 routed to an ipsecN network interface. Pluto only uses normal routing
21 (as opposed to "Advanced Routing"), so the selection of packets is
22 made solely on the basis of the destination address. (Since the
23 actual routing commands are in the updown script, they could be
24 changed by the administrator, but Pluto needs to understand what is
25 going on, and it currently assumes normal routing is used.)
27 When an outbound packet hits an ipsecN interface, KLIPS figures out
28 how to process it by finding an eroute that applies to the source and
29 destination addresses. Eroutes are global: they are not specific to a
30 particular ipsecN interface (routing needs to get the packets to any
31 ipsecN interface; erouting takes it from there, ignoring issues of
32 source IP address and nexthop (because nobody knows!)). If multiple
33 eroutes apply to the packet, among the ones with the most specific
34 source subnet, the one with the most specific destination subset is
35 chosen (RGB thinks). If no eroute is discovered, KLIPS acts as if it
36 was covered by a DROP eroute (this is the default behaviour; it can be
37 changed). At most one eroute can exist for a particular pair of
40 There are fundamentally two kinds of eroutes: "shunt" eroutes and ones
41 that specify that a packet is to be processed by a group of IPSEC SAs.
42 Shunt eroutes specify what is to be done with the packet. Remember
43 that these only apply to outbound packets.
45 - TRAP: notify Pluto of the packet (presumably to attempt to negotiate
46 an appropriate group of IPSEC SAs). At the same time, KLIPS
47 installs a HOLD shunt (see below) for the specific source and
48 destination addresses from the packet and retains the packet
49 for later reprocessing (KLIPS does not yet implement retention).
50 Beware: if the TRAP's subnets both contained a single IP address
51 then installing the HOLD would actually delete the TRAP.
53 - PASS: let the packet through in the clear
55 - DROP: discard the packet
57 - REJECT: discard the packet and notify the sender
59 - HOLD: (automatically created by KLIPS when a TRAP fires) block
60 the packet, but retain it. If there is already a retained
61 packet, drop the old one and retain the new. When the HOLD
62 shunt is deleted or replaced, the retained packet is reinjected --
63 there might now be a tunnel. Note that KLIPS doesn't yet
64 implement the retention part, so HOLD is really like a DROP.
66 One consequence of there being only one eroute for a pair of clients
67 is that KLIPS will only use one SA group for output for this pair,
68 even though there could be several SA groups that are authorised and
69 live. Pluto chooses to make this the youngest such group.
73 KLIPS lets through in the clear outbound UDP/500 packets that would
74 otherwise be processed if they originate on this host and meet certain
75 other conditions. The actual test is
77 && (no_eroute || dest == eroute.dest || isanyaddr(eroute.dest))
79 The idea is that IKE packets between us and a peer should not be
80 sent through an IPSEC tunnel negotiated between us. Furthermore,
81 our shunt eroutes should not apply to our IKE packets (shunt eroutes
82 will generally have an eroute.dest of 0.0.0.0 or its IPv6 equivalent).
84 Inbound behaviour is controlled in a quite different way. KLIPS
85 processes only those inbound packets of ESP or AH protocol, with a
86 destination address for this machine's ipsecN interfaces. The
87 processing is as dictated by the SAs involved. Unfortunately, the
88 decapsulated packet's source and destination address are not checked
89 (part of "inbound policy checking").
91 To prevent clear packets being accepted, firewall rules must be put in
92 place. This has nothing to do with KLIPS, but is nonetheless in
93 important part of security. It isn't clear what firewalling makes
94 sense when Opportunism is allowed.
97 For routing and firewalling, Pluto invokes the updown script. Pluto
98 installs eroutes via extended PF_KEY messages.
101 Current Pluto Behaviour
102 -----------------------
106 Routes and most eroutes are associated with connections (struct
107 connection, a potential connection description). The enum routing_t
108 field "routing" in struct connection records the state of routing and
109 erouting for that connection. The values are:
110 RT_UNROUTED, /* unrouted */
111 RT_UNROUTED_HOLD, /* unrouted, but HOLD shunt installed */
112 RT_ROUTED_PROSPECTIVE, /* routed, and TRAP shunt installed */
113 RT_ROUTED_HOLD, /* routed, and HOLD shunt installed */
114 RT_ROUTED_FAILURE, /* routed, and failure-context shunt installed */
115 RT_ROUTED_TUNNEL /* routed, and erouted to an IPSEC SA group */
116 Notice that the routing and erouting are not independent: erouting
117 (except for HOLD) implies that the connection is routed.
119 Several struct connections may have the same destination subnet. If
120 they agree on what the route should be, they can share it -- any of
121 them may have routing >= RT_ROUTED_PROSPECTIVE. If they disagree,
122 they cannot simultaneously be routed.
124 invariant: for all struct connections c, d:
125 (c.that.client == d.that.client
126 && c.routing >= RT_ROUTED_PROSPECTIVE
127 && d.routing >= RT_ROUTED_PROSPECTIVE)
128 => c.interface == d.interface && c.this.nexthop == d.this.nexthop
130 There are two kinds of eroutes: shunt eroutes and ones for an IPSEC SA
131 Group. Most eroutes are associated with and are represeented in a
132 connection. The exception is that some HOLD and PASS shunts do not
133 correspond to connections; those are represented in the bare_shunt
136 An eroute for an IPSEC SA Group is associated with the state object
137 for that Group. The existence of such an eroute is also represented
138 by the "so_serial_t eroute_owner" field in the struct connection. The
139 value is the serial number of the state object for the Group. The
140 special value SOS_NOBODY means that there is no owner associated with
141 this connection for the eroute and hence no normal eroute. At most
142 one eroute owner may exist for a particular (source subnet,
143 destination subnet) pair. A Pluto-managed eroute cannot be associated
144 with an RT_UNROUTED connection.
146 invariant: for all struct connection c:
147 c.routing == RT_EROUTED_TUNNEL || c.eroute_owner == SOS_NOBODY
149 invariant: for all struct connections c, d:
150 c.this.client == d.this.client && c.that.client == d.that.client
152 => c.routing == RT_UNROUTED || d.routing == RT_UNROUTED
154 If no normal eroute is set for a particular (source subnet,
155 destination subnet) pair for which a connection is routed, then a
156 shunt eroute would have been installed. This specifies what should
157 happen to packets snared by the route.
159 When Pluto is notified by KLIPS of a packet that has been TRAPped,
160 there is no connection with which to associate the HOLD. It is
161 temporarily held in the "bare_shunt table". If Opportunism is
162 attempted but DNS doesn't provide Security Gateway information, Pluto
163 will replace the HOLD with a PASS shunt. Since this PASS isn't
164 associated with a connection, it too will reside in the bare_shunt
165 table. If the HOLD can be associated with a connection, it will be
166 removed from the bare_shunt table and represented in the connection.
168 There are two contexts for which shunt eroutes are installed by Pluto
169 for a particular connection. The first context is with the prospect
170 of dealing with packets before any negotiation has been attempted. I
171 call this context "prospective". Currently is a TRAP shunt, used to
172 catch packets for initiate opportunistic negotiation. In the future,
173 it might also be used to implement preordained PASS, DROP, or REJECT
176 The second context is after a failed negotiation. I call this context
177 "failure". At this point a different kind of shunt eroute is
178 appropriate. Depending on policy, it could be PASS, DROP, or REJECT,
179 but it is unlikely to be TRAP. The shunt eroute should have a
180 lifetime (this isn't yet implemented). When the lifetime expires, the
181 failure shunt eroute should be replaced by the prospective shunt
184 The kind and duration of a failure shunt eroute should perhaps depend
185 on the nature of the failure, at least as imperfectly detected by
186 Pluto. We haven't looked at this. In particular, the mapping from
187 observations to robust respose isn't obvious.
189 The shunt eroute policies should be a function of the potential
190 connection. The failure shunt eroute can be specified for a
191 particular connection with the flags --pass and --drop in a connection
192 definition. There are four combinations, and each has a distinct
193 meaning. The failure shunt eroute is incompletely implemented and
194 cannot be represented in /etc/ipsec.conf.
196 There is as yet no control over the prospective shunt eroute: it is
197 always TRAP as far as Pluto is concerned. This is probably
198 reasonable: any other fate suggests that no negotiation will be done,
199 and so a connection definition is inappropriate. These should be
200 implemented as manual conns. There remains the issue of whether Pluto
201 should be aware of them -- currently it is not.
208 bool do_command(struct connection *c, const char *verb)
209 Run the updown script to perform such tasks as installing a route
210 and adjust the firewall.
212 bool could_route(struct connection *c)
213 Check to see whether we could route and eroute the connection.
214 <- shunt_eroute_connection (to check if --route can be performed)
215 <- install_inbound_ipsec_sa (to see if it will be possible
216 to (later) install route and eroute the corresponding outbound SA)
217 <- install_ipsec_sa (to see if the outbound SA can be routed and erouted)
219 bool trap_connection(struct connection *c)
220 Install a TRAP shunt eroute for this connection. This implements
221 "whack --route", the way an admin can specify that packets for a
222 connection should be caught without first bringing it up.
224 void unroute_connection(struct connection *c)
225 Delete any eroute for a connection and unroute it if route isn't shared.
226 <- release_connection
227 <- whack_handle (for "whack --unroute)
229 bool eroute_connection(struct connection *c
230 , ipsec_spi_t spi, unsigned int proto, unsigned int satype
231 , unsigned int op, const char *opname UNUSED)
232 Issue PF_KEY commands to KLIPS to add, replace, or delete an eroute.
233 The verb is specified by op and described (for logging) by opname.
238 bool assign_hold(struct connection *c
239 , const ip_address *src, const ip_address *dst)
240 Take a HOLD from the bare_shunt table and assign it to a connection.
241 If the HOLD is broadened (i.e. the connection's source or destination
242 subnets contain more than one IP address), this will involve replacing
243 the HOLD with a different one.
245 bool sag_eroute(struct state *st, unsigned op, const char *opname)
246 SA Group eroute manipulation. The SA Group concerned is
247 identified with a state object.
248 <- route_and_eroute several times
250 bool shunt_eroute(struct connection *c, unsigned int op, const char *opname)
251 shunt eroute manipulation. Shunt eroutes are associated with
253 <- unroute_connection
257 bool route_and_eroute(struct connection *c, struct state *st)
258 Install a route and then a prospective shunt eroute or an SA group
259 eroute. The code assumes that could_route had previously
260 given the go-ahead. Any SA group to be erouted must already
262 <- shunt_eroute_connection
265 void scan_proc_shunts(void)
266 Every SHUNT_SCAN_INTERVAL scan /proc/net/ipsec_eroute.
267 Delete any PASS eroute in the bare_shunt table that hasn't been used
268 within the last SHUNT_PATIENCE seconds.
269 For any HOLD for which Pluto hasn't received an ACQUIRE (possibly
270 lost due to congestion), act as if an ACQUIRE were received.
274 struct connection *route_owner(struct connection *c, struct connection **erop)
275 Find the connection to connection c's peer's client with the
276 largest value of .routing. All other things being equal,
277 preference is given to c. Return NULL if no connection is routed
278 at all. If erop is non-null, sets it to a connection sharing both
279 our client subnet and peer's client subnet with the largest value
281 The return value is used to find other connections sharing
282 a route. The value of *erop is used to find other connections
284 <- could_route (to find any conflicting routes or eroutes)
285 <- unroute_connection (to find out if our route is still in use
286 after this connection is finished with it)
287 <- install_inbound_ipsec_sa (to find other IPSEC SAs for the
288 same peer clients; when we find them WE KILL THEM; a
289 kludge to deal with road warriors reconnecting)
290 <- route_and_eroute (to find all the connections from which the
291 route or eroute is being stolen)
295 - setting up route & shunt eroute to TRAP packets for opportunism
296 (whack --route). Perhaps also manually designating DROP, REJECT, or
297 PASS for certain packets.
299 whack_handle() responds to --route; calls route_connection()
302 - removing same (whack --unroute)
304 whack_handle() responds to --unroute; calls unroute_connection()
306 - installing route & normal eroute for a newly negotiated group of
309 + perhaps an (additional) route is not needed: if the negotiation
310 was initiated by a TRAPped outgoing packet, then there must
311 already have been a route that got the packet to ipsecN. Mind
312 you, it could have been the wrong N!
316 - updating a normal eroute when a new group of IPSEC SAs replaces
317 an old one due to rekeying.
321 - replacing an old eroute when a negotiation fails. But this is
322 tricky. If this was a rekeying, we should just leave the old
323 normal eroute be -- it might still work. Otherwise, this was
324 an initial negotiation: we should replace the shunt eroute
325 with one appropriate for the failure context.
327 - when a group of IPSEC SAs dies or is killed, and it had the eroute,
328 its normal eroute should be replaced by a shunt eroute. If there
329 was an attempt to replace the group, the replacement is in the
330 failure context; otherwise the replacement is in the prospective