freeswan/doc/firewall.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
   2 <HTML>
   3 <HEAD>
   4 <TITLE> Introduction to FreeS/WAN</TITLE>
   5 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   6 </HEAD>
   7 <BODY>
   8 <A HREF="toc.html">Contents</a>
   9 <A HREF="manpages.html">Previous</a>
  10 <A HREF="trouble.html">Next</a>
  11 <HR>
  12 <H1><A name="firewall">FreeS/WAN and firewalls</A></H1>
  13 <P> FreeS/WAN, or other IPSEC implementations, frequently run on
  14 gateway  machines, the same machines running firewall or packet
  15 filtering code. This  document discusses the relation between the two.</P>
  16 <H2><A name="packets">IPSEC packets</A></H2>
  17 <P>IPSEC uses three main types of packet:</P>
  18 <DL>
  19 <DT><A href="glossary.html#IKE">IKE</A> uses <STRONG>the UDP protocol
  20 and port  500</STRONG>.</DT>
  21 <DD>Unless you are using only (less secure, not recommended) manual
  22  keying, you need IKE to negotiate connection parameters, acceptable
  23  algorithms, key sizes and key setup. IKE handles everything required
  24  to set up, rekey, repair or tear down IPSEC connections.</DD>
  25 <DT><A href="glossary.html#ESP">ESP</A> is <STRONG>protocol number 50</STRONG>
  26 </DT>
  27 <DD>This is required for encrypted connections.</DD>
  28 <DT><A href="glossary.html#AH">AH</A> is <STRONG>protocol number 51</STRONG>
  29 </DT>
  30 <DD>This can be used where only authentication, not encryption, is
  31  required. That can also be done with ESP and null encryption.</DD>
  32 </DL>
  33 <P> All of those packets should have appropriate IPSEC gateway
  34 addresses in both the to and from IP header fields. Firewall rules can
  35 check this if you wish, though it is not strictly necessary. This is
  36 discussed in more detail <A href="#unknowngate">later</A>. </P>
  37 <P> IPSEC processing of incoming packets authenticates them then
  38 removes the ESP or AH header and decrypts if necessary. Successful
  39 processing exposes an inner packet which is then delivered back to the
  40 firewall machinery, marked as having arrived on an <VAR>ipsec[0-3]</VAR>
  41  interface. Firewall rules can use that interface label to distinguish
  42 these packets from unencrypted packets which are labelled with the
  43 physical interface they arrived on (or perhaps with a non-IPSEC virtual
  44 interface such as <VAR>ppp0</VAR>).</P>
  45 <P> One of our users sent a mailing list message with a <A href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/12/msg00006.html">
  46 diagram</A> of the packet flow. </P>
  47 <H3><A name="noport">ESP and AH do not have ports</A></H3>
  48 <P> Some protocols, such as TCP and UDP, have the notion of ports.
  49 Others protocols, including ESP and AH, do not. Quite a few IPSEC
  50 newcomers have  become confused on this point. There are no ports <EM>in</EM>
  51  the ESP or AH  protocols, and no ports used <EM>for</EM> them. For
  52 these protocols, <EM>the  idea of ports is completely irrelevant</EM>.</P>
  53 <H3><A name="header">Header layout</A></H3>
  54 <P>The protocol numbers for ESP or AH are used in the 'next header'
  55 field of  the IP header. On most non-IPSEC packets, that field would
  56 have one of:</P>
  57 <UL>
  58 <LI>1 for ICMP</LI>
  59 <LI>4 for IP-in-IP encapsulation</LI>
  60 <LI>6 for TCP</LI>
  61 <LI>17 for UDP</LI>
  62 <LI>... or one of about 100 other possibilities listed by <A href="http://www.isi.edu/in-notes/iana/assignments/protocol-numbers">
  63 IANA</A></LI>
  64 </UL>
  65 <P>Each header in the sequence tells what the next header will be.
  66 IPSEC  adds headers for ESP or AH near the beginning of the sequence.
  67 The original  headers are kept and the 'next header' fields adjusted so
  68 that all headers  can be correctly interpreted.</P>
  69 <P>For example, using <STRONG>[</STRONG><STRONG> ]</STRONG> to indicate
  70 data  protected by ESP and unintelligible to an eavesdropper between
  71 the  gateways:</P>
  72 <UL>
  73 <LI>a simple packet might have only IP and TCP headers with:
  74 <UL>
  75 <LI>IP header says next header --&gt; TCP</LI>
  76 <LI>TCP header port number --&gt; which process to send data to</LI>
  77 <LI>data</LI>
  78 </UL>
  79 </LI>
  80 <LI>with ESP <A href="glossary.html#transport">transport mode</A>
  81  encapsulation, that  packet would have:
  82 <UL>
  83 <LI>IP header says next header --&gt; ESP</LI>
  84 <LI>ESP header <STRONG>[</STRONG> says next --&gt; TCP</LI>
  85 <LI>TCP header port number --&gt; which process to send data to</LI>
  86 <LI>data <STRONG>]</STRONG></LI>
  87 </UL>
  88  Note that the IP header is outside ESP protection, visible to an
  89  attacker, and that the final destination must be the gateway.</LI>
  90 <LI>with ESP in <A href="glossary.html#tunnel">tunnel mode</A>, we
  91 might have:
  92 <UL>
  93 <LI>IP header says next header --&gt; ESP</LI>
  94 <LI>ESP header <STRONG>[</STRONG> says next --&gt; IP</LI>
  95 <LI>IP header says next header --&gt; TCP</LI>
  96 <LI>TCP header port number --&gt; which process to send data to</LI>
  97 <LI>data <STRONG>]</STRONG></LI>
  98 </UL>
  99  Here the inner IP header is protected by ESP, unreadable by an
 100 attacker.  Also, the inner header can have a different IP address than
 101 the outer IP  header, so the decrypted packet can be routed from the
 102 IPSEC gateway to  a final destination which may be another machine.</LI>
 103 </UL>
 104 <P> Part of the ESP header itself is encrypted, which is why the <STRONG>
 105 [</STRONG> indicating protected data appears in the middle of some
 106 lines above. The next header field of the ESP header is protected. This
 107 makes <A href="glossary.html#traffic">traffic analysis</A> more
 108 difficult. The next header field would tell an eavesdropper whether
 109 your packet was UDP to the gateway, TCP to the gateway, or encapsulated
 110 IP. It is better not to give this information away. A clever attacker
 111 may deduce some of it from the pattern of packet sizes and timings, but
 112 we need not make it easy. </P>
 113 <P> IPSEC allows various combinations of these to match local policies,
 114 including combinations that use both AH and ESP headers or that nest
 115 multiple copies of these headers.</P>
 116 <P> For example, suppose my employer has an IPSEC VPN running between
 117 two offices so all packets travelling between the gateways for those
 118 offices are encrypted. If gateway policies allow it (The admins could
 119 block UDP 500 and protocols 50 and 51 to disallow it), I can build an
 120 IPSEC tunnel from my desktop to a machine in some remote office. Those
 121 packets will have one ESP header throughout their life, for my
 122 end-to-end tunnel. For part of the route, however, they will also have
 123 another ESP layer for the corporate VPN's encapsulation. The whole
 124 header scheme for a packet on the Internet might be:</P>
 125 <UL>
 126 <LI>IP header (with gateway address) says next header --&gt; ESP</LI>
 127 <LI>ESP header <STRONG>[</STRONG> says next --&gt; IP</LI>
 128 <LI>IP header (with receiving machine address) says next header --&gt;  ESP</LI>
 129 <LI>ESP header <STRONG>[</STRONG> says next --&gt; TCP</LI>
 130 <LI>TCP header port number --&gt; which process to send data to</LI>
 131 <LI>data <STRONG>]]</STRONG></LI>
 132 </UL>
 133 <P> The first ESP (outermost) header is for the corporate VPN. The
 134 inner ESP header is for the secure machine-to-machine link.</P>
 135 <H2><A name="filters">Filtering rules for IPSEC packets</A></H2>
 136 <P> As a consequence of the above, an IPSEC gateway should have packet
 137 filters that allow the following protocols when talking to other IPSEC
 138 gateways:</P>
 139 <UL>
 140 <LI>UDP port 500</LI>
 141 <LI>protocol 50 if you use ESP encryption and/or authentication (the
 142  typical case)</LI>
 143 <LI>protocol 51 if you use AH packet-level authentication</LI>
 144 </UL>
 145 <P> Your gateway and the other IPSEC gateways it communicates with must
 146 be able to exchange these packets for IPSEC to work. Firewall rules
 147 must allow UDP 500 and at least one of AH or ESP on the interface that
 148 communicates with the other gateway. </P>
 149 <H3><A name="through">IPSEC <EM>through</EM></A> the gateway</H3>
 150 <P> The preceeding paragraph deals with packets <EM>addressed to or
 151 sent from  your gateway</EM>. It is a separate policy decision whether
 152 to permit such  packets to pass <EM>through</EM> the gateway so that
 153 client machines can  build end-to-end IPSEC tunnels of their own. This
 154 may not be practical if  you are using <A href="#NAT">NAT (IP
 155 masquerade)</A> on your gateway, and  may conflict with some corporate
 156 security policies. Other than that, it is  likely a good idea.</P>
 157 <H3><A name="ipsec_only">Preventing non-IPSEC traffic</A></H3>
 158  You can of course also filter <EM>everything but</EM> UDP port 500 and
 159 ESP or AH to restrict traffic to IPSEC only, either for anyone
 160 communicating with your host or just for specific partners.
 161 <H3><A name="unknowngate">Filtering packets from unknown gateways</A></H3>
 162 <P> It is possible to use firewall rules to restrict UDP 500, ESP and
 163 AH packets so that these packets are accepted only from known gateways.
 164 This is not strictly necessary since FreeS/WAN will discard packets
 165 from unknown gateways. You might, however, want to do it for any of a
 166 number of reasons. For example:</P>
 167 <UL>
 168 <LI>Arguably, &quot;belt and suspenders&quot; is the sensible approach to
 169 security.  If you can block a potential attack in two ways, use both.
 170 The only  question is whether to look for a third way after
 171 implementing the first  two.</LI>
 172 <LI>Some admins may prefer to use the firewall code this way because
 173 they  prefer firewall logging to FreeS/WAN's logging.</LI>
 174 <LI>You may need it to implement your security policy. Consider an
 175  employee working at home, and a policy that says traffic from the home
 176  system to the Internet at large must go first via IPSEC to the
 177 corporate  LAN and then out to the Internet via the corporate firewall.
 178 One way to  do that is to make <VAR>ipsec0</VAR> the default route on
 179 the home  gateway and provide exceptions only for UDP 500 and ESP to
 180 the corporate  gateway. Everything else is then routed via the tunnel
 181 to the corporate  gateway.</LI>
 182 </UL>
 183 <P>It is not possible to use only static firewall rules for this
 184 filtering  if you do not know the other gateways' IP addresses in
 185 advance, for example  if you have &quot;road warriors&quot; who may connect from
 186 a different address each  time or if want to do <A href="glossary.html#carpediem">
 187 opportunistic encryption</A> to  arbitrary gateways. In these cases,
 188 you can accept UDP 500 IKE packets from  anywhere, then use the <A href="#updown">
 189 updown</A> script feature of <A href="manpage.d/ipsec_pluto.8.html">
 190 pluto(8)</A> to dynamically adjust  firewalling for each negotiated
 191 tunnel.</P>
 192 <P>Firewall packet filtering does not much reduce the risk of a <A href="glossary.html#DOS">
 193 denial of service attack</A> on FreeS/WAN. The firewall can drop
 194  packets from unknown gateways, but KLIPS does that quite efficiently
 195 anyway,  so you gain little. The firewall cannot drop otherwise
 196 legitmate packets  that fail KLIPS authentication, so it cannot protect
 197 against an attack  designed to exhaust resources by making FreeS/WAN
 198 perform many expensive  authentication operations.</P>
 199 <P>In summary, firewall filtering of IPSEC packets from unknown
 200 gateways is  possible but not strictly necessary.</P>
 201 <H2><A name="otherfilter">Other packet filters</A></H2>
 202 <P>When the IPSEC gateway is also acting as your firewall, other packet
 203  filtering rules will be in play. In general, those are outside the
 204 scope of  this document. See our <A href="web.html#firewall">Linux
 205 firewall links</A> for  information. There are a few types of packet,
 206 however, which can affect the  operation of FreeS/WAN or of diagnostic
 207 tools commonly used with it. These  are discussed below.</P>
 208 <H3><A name="ICMP">ICMP filtering</A></H3>
 209 <P><A href="glossary.html#ICMP">ICMP</A> is the <STRONG>I</STRONG>
 210 nternet <STRONG>C</STRONG>ontrol <STRONG>M</STRONG>essage <STRONG>P</STRONG>
 211 rotocol. It is used for messages between IP implementations themselves,
 212 whereas IP used is used between the clients of those implementations.
 213 ICMP is, unsurprisingly, used for control messages. For example, it is
 214 used to notify a sender that a desination is not reachable, or to tell
 215 a router to reroute certain packets elsewhere. </P>
 216 <P> ICMP handling is tricky for firewalls. </P>
 217 <UL>
 218 <LI>You definitely want some ICMP messages to get through; things won't
 219 work without them. For example, your clients need to know if some
 220 destination they ask for is unreachable. </LI>
 221 <LI>On the other hand, you do equally definitely do not want untrusted
 222 folk sending arbitrary control messages to your machines. Imagine what
 223 someone moderately clever and moderately malicious could do to you,
 224 given control of your network's routing. </LI>
 225 </UL>
 226 <P>ICMP does not use ports. Messages are distinguished by a &quot;message
 227 type&quot;  field and, for some types, by an additional &quot;code&quot; field. The
 228 definitive  list of types and codes is on the <A href="http://www.isi.edu/in-notes/iana/assignments/icmp-parameters">
 229 IANA</A> site.</P>
 230 <P>One expert uses this definition for ICMP message types to be dropped
 231 at  the firewall.</P>
 232 <PRE>
 233 # ICMP types which lack socially redeeming value.
 234 #  5     Redirect
 235 #  9     Router Advertisement
 236 # 10     Router Selection
 237 # 15     Information Request
 238 # 16     Information Reply
 239 # 17     Address Mask Request
 240 # 18     Address Mask Reply
 241
 242 badicmp='5 9 10 15 16 17 18'
 243 </PRE>
 244 <P> A more conservative approach would be to make a list of allowed
 245 types and drop everything else.</P>
 246 <P>Whichever way you do it, your ICMP filtering rules on a FreeS/WAN
 247 gateway  should allow at least the following ICMP packet types:</P>
 248 <DL>
 249 <DT>echo (type 8)</DT>
 250 <DD>
 251 <DT>echo reply (type 0)</DT>
 252 <DD>These are used by ping(1). We recommend allowing both types through
 253  the tunnel and to or from your gateway's external interface, since
 254  ping(1) is an essential testing tool. </DD>
 255 <P>It is fairly common for firewalls to drop ICMP echo packets
 256  addressed to machines behind the firewall. If that is your policy,
 257  please create an exception for such packets arriving via an IPSEC
 258  tunnel, at least during intial testing of those tunnels.</P>
 259 <DT>destination unreachable (type 3)</DT>
 260 <DD>This is used, with code 4 (Fragmentation Needed and Don't Fragment
 261  was Set) in the code field, to control <A href="glossary.html#pathMTU">
 262 path MTU  discovery</A>. Since IPSEC processing adds headers, enlarges
 263 packets  and may cause fragmentation, an IPSEC gateway should be able
 264 to send  and receive these ICMP messages <STRONG>on both inside and
 265 outside  interfaces</STRONG>.</DD>
 266 </DL>
 267 <H3><A name="traceroute">UDP packets for traceroute</A></H3>
 268 <P> The traceroute(1) utility uses UDP port numbers from 33434 to
 269 approximately 33633. Generally, these should be allowed through for
 270 troubleshooting.</P>
 271 <P> Some firewalls drop these packets to prevent outsiders exploring
 272 the protected network with traceroute(1). If that is your policy,
 273 consider creating an exception for such packets arriving via an IPSEC
 274 tunnel, at least during intial testing of those tunnels.</P>
 275 <H3><A name="l2tp">UDP for L2TP</A></H3>
 276  Windows 2000 does, and products designed for compatibility with it
 277 may, build <A href="glossary.html#L2TP">L2TP</A> tunnels over IPSEC
 278 connections.
 279 <P> For this to work, you must allow UDP protocol 1701 packets coming
 280 out of your tunnels to continue to their destination. You can, and
 281 probably should, block such packets to or from your external
 282 interfaces, but allow them from <VAR>ipsec0</VAR>. </P>
 283 <P> See also our Windows 2000 <A href="interop.html#win2k">
 284 interoperation discussion</A>. </P>
 285 <H2><A name="NAT">IPSEC and NAT</A></H2>
 286 <P><A href="glossary.html#NAT"> Network Address Translation</A>, also
 287 known as IP masquerading, is a method of allocating IP addresses
 288 dynamically, typically in circumstances where the total number of
 289 machines which need to access the Internet exceeds the supply of IP
 290 addresses.</P>
 291 <P> Any attempt to perform NAT operations on IPSEC packets <EM>between
 292 the  IPSEC gateways</EM> creates a basic conflict:</P>
 293 <UL>
 294 <LI>IPSEC wants to authenticate packets and ensure they are unaltered
 295 on a  gateway-to-gateway basis</LI>
 296 <LI>NAT rewrites packet headers as they go by</LI>
 297 <LI>IPSEC authentication fails if packets are rewritten anywhere
 298 between  the IPSEC gateways</LI>
 299 </UL>
 300  For <A href="glossary.html#AH">AH</A>, which authenticates parts of
 301 the packet header including source and destination IP addresses, this
 302 is fatal. If NAT changes those fields, AH authentication fails.
 303 <P> For <A href="glossary.html#IKE">IKE</A> and <A href="glossary.html#ESP">
 304 ESP</A> it is not necessarily fatal, but is certainly an unwelcome
 305 complication. </P>
 306 <H3><A name="nat_ok">NAT on or behind the IPSEC gateway works</A></H3>
 307 <P> This problem can be avoided by having the masquerading take place <EM>
 308 on or behind</EM> the IPSEC gateway. </P>
 309 <P> This can be done physically with two machines, one physically
 310 behind the other. A picture, using SG to indicate IPSEC <STRONG>S</STRONG>
 311 ecurity <STRONG>G</STRONG>ateways, is: </P>
 312 <PRE>
 313       clients --- NAT ----- SG ---------- SG
 314                   two machines
 315 </PRE>
 316 <P> In this configuration, the actual client addresses need not be
 317 given in the <VAR>leftsubnet=</VAR> parameter of the FreeS/WAN
 318 connection description. The security gateway just delivers packets to
 319 the NAT box; it needs only that machine's address. What that machine
 320 does with them does not affect FreeS/WAN. </P>
 321 <P> A more common setup has one machine performing both functions:</P>
 322 <PRE>
 323       clients ----- NAT/SG ---------------SG
 324                   one machine
 325 </PRE>
 326  Here you have a choice of techniques depending on whether you want to
 327 make your client subnet visible to clients on the other end:
 328 <UL>
 329 <LI>If you want the single gateway to behave like the two shown above,
 330 with your clients hidden behind the NAT, then omit the <VAR>leftsubnet=</VAR>
 331  parameter. It then defaults to the gateway address. Clients on the
 332 other end then talk via the tunnel only to your gateway. The gateway
 333 takes packets emerging from the tunnel, applies normal masquerading,
 334 and forwards them to clients. </LI>
 335 <LI>If you want to make your client machines visible, then give the
 336 client subnet addresses as the <VAR>leftsubnet=</VAR> parameter in the
 337 connection description and
 338 <DL>
 339 <DT>either </DT>
 340 <DD>set <VAR>leftfirewall=yes</VAR> to use the default <VAR>updown</VAR>
 341  script </DD>
 342 <DT>or </DT>
 343 <DD>use your own script by giving its name in a <VAR>leftupdown=</VAR>
 344  parameter </DD>
 345 </DL>
 346  These scripts are described in their own <A href="#updown">section</A>
 347 . </LI>
 348 <P> In this case, no masquerading is done. Packets to or from the
 349 client subnet are encrypted or decrypted without any change to their
 350 client subnet addresses, although of course the encapsulating packets
 351 use gateway addresses in their headers. Clients behind the right
 352 security gateway see a route via that gateway to the left subnet.</P>
 353 </UL>
 354 <H3><A name="nat_bad">NAT between gateways is problematic</A></H3>
 355 <P> We recommend not trying to build IPSEC connections which pass
 356 through a NAT machine. This setup poses problems:</P>
 357 <PRE>
 358       clients --- SG --- NAT ---------- SG
 359 </PRE>
 360  If you must try it, some references are:
 361 <UL>
 362 <LI>Jean_Francois Nadeau's document on doing <A href="http://jixen.tripod.com/#NATed gateways">
 363 IPSEC behind NAT</A></LI>
 364 <LI><A href="web.html#VPN.masq">VPN masquerade patches</A> to make a
 365 Linux NAT box handle IPSEC packets correctly </LI>
 366 </UL>
 367 <H3><A name="">Other references on NAT and IPSEC</A></H3>
 368  Other documents which may be relevant include:
 369 <UL>
 370 <LI>an Internet Draft on <A href="http://search.ietf.org/internet-drafts/draft-aboba-nat-ipsec-04.txt">
 371 IPSEC and NAT</A> which may eventually evolve into a standard solution
 372 for this problem. </LI>
 373 <LI>an informational <A href="http://www.cis.ohio-state.edu/rfc/rfc2709.txt">
 374 RFC</A>, <CITE>Security Model with Tunnel-mode IPsec for NAT Domains</CITE>
 375 . </LI>
 376 <LI>an <A href="http://www.cisco.com/warp/public/759/ipj_3-4/ipj_3-4_nat.html">
 377 article</A> in Cisco's <CITE>Internet Protocol Journal</CITE></LI>
 378 </UL>
 379 <H2><A name="updown">Calling firewall scripts, named in ipsec.conf(5)</A>
 380 </H2>
 381 <P> The <A href="manpage.d/ipsec.conf.5.html">ipsec.conf</A>
 382  configuration file has three pairs of parameters used to specify an
 383 interface between FreeS/WAN and firewalling code.</P>
 384 <P> Note that using these is not required if you have a static firewall
 385 setup. In that case, you just set your firewall up at boot time (in a
 386 way that permits the IPSEC connections you want) and do not change it
 387 thereafter. Omit all the FreeS/WAN firewall parameters and FreeS/WAN
 388 will not attempt to adjust firewall rules at all. See <A href="#examplefw">
 389 below</A> for some information on appropriate scripts. </P>
 390 <P> However, if you want your firewall rules to change when IPSEC
 391 connections change, then you need to use these parameters. </P>
 392 <H3><A name="pre_post">Scripts called at IPSEC start and stop</A></H3>
 393 <P> One pair of parmeters are set in the <VAR>config setup</VAR>
 394  section of the <A href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A>
 395  file and affect all connections:</P>
 396 <DL>
 397 <DT>prepluto=</DT>
 398 <DD>
 399 <DT>postpluto=</DT>
 400 <DD>specify scripts to be called before our <A href="manpage.d/ipsec_pluto.8.html">
 401 pluto(8)</A> IKE daemon is started and after it is stopped.</DD>
 402 </DL>
 403  These parameters allow you to change firewall parameters whenever
 404 IPSEC is started or stopped.
 405 <P> They can also be used in other ways. For example, you might have <VAR>
 406 prepluto</VAR> add a module to your kernel for the secure network
 407 interface or make a dialup connection, and then have <VAR>postpluto</VAR>
 408  remove the module or take the connection down. </P>
 409 <H3><A name="up_down">Scripts called at connection up and down</A></H3>
 410 <P> The other parameters are set in connection descriptions. They can
 411 be set in individual connection descriptions, and could even call
 412 different scripts for each connection for maximum flexibility. In most
 413 applications, however, it makes sense to use only one script and to
 414 call it from <VAR>conn %default</VAR> section so that it applies to all
 415 connections. </P>
 416 <P> You can either set <VAR>[left|right]firewall=yes</VAR> to use our
 417 supplied default script or assign a name in a <VAR>[left|right]updown=</VAR>
 418  line to use your own script. </P>
 419 <P> For details of when Pluto calls these scripts, what arguments it
 420 passes to them, and what the default script does with those arguments,
 421 see the <A href="manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</A> man
 422 page. </P>
 423 <P> Note that <STRONG>only one of these should be used</STRONG>. You
 424 cannot sensibly use both. </P>
 425 <H4><A name="">The default script</A></H4>
 426  We supply a default script named <VAR>_updown</VAR>.
 427 <DL>
 428 <DT>leftfirewall=</DT>
 429 <DD>
 430 <DT>rightfirewall=</DT>
 431 <DD>indicates that the gateway is doing firewalling and that <A href="manpage.d/ipsec_pluto.8.html">
 432 pluto(8)</A> should poke holes in  the firewall as required. </DD>
 433 </DL>
 434  Set these to <VAR>yes</VAR> and Pluto will call our default script <VAR>
 435  _updown</VAR> with appropriate arguments whenever it:
 436 <UL>
 437 <LI>starts or stops IPSEC services</LI>
 438 <LI>brings a connection up or down</LI>
 439 </UL>
 440  The supplied default <VAR>_updown</VAR> script is appropriate for
 441 simple cases using the <VAR>ipfwadm(8)</VAR> firewalling package.
 442 <H4><A name="userscript">User-written scripts</A></H4>
 443  You can also write your own script and have Pluto call it. Just put
 444 the script's name in one of these <A href="manpage.d/ipsec.conf.5.html">
 445 ipsec.conf(5)</A> lines:
 446 <DL>
 447 <DT>leftupdown=</DT>
 448 <DD>
 449 <DT>rightupdown=</DT>
 450 <DD>specifies a script to call instead of our default script <VAR>
 451  _updown</VAR>.</DD>
 452 </DL>
 453  Your script should take the same arguments and use the same
 454 environment variables as <VAR>_updown</VAR>. These are described in the <A
 455 href="manpage.d/ipsec_pluto.8.html">pluto(8)</A> man page.
 456 <P> In developing your own script, you can of course use our scripts
 457 (either the default _updown or the ipchains-based example given <A href="#exupdownchains">
 458 below</A>) as a starting point. Note, however, that <STRONG>you should
 459 not modify our _updown script in place</STRONG>. If you did that, then
 460 upgraded FreeS/WAN, the upgrade would install a new default script,
 461 overwriting your changes. </P>
 462 <H3><A name="ipchains.script">Scripts for ipchains</A></H3>
 463 <P> Our <VAR>_updown</VAR> is for firewalls using <VAR>ipfwadm(8)</VAR>
 464 . If you are using the more recent package <VAR>ipchains(8)</VAR>, you
 465 must do one of: </P>
 466 <UL>
 467 <LI>use static firewall rules which require no change for FreeS/WAN </LI>
 468 <LI>limit yourself to ipchains(8)'s ipfwadm(8) emulation mode in  order
 469 to use our script </LI>
 470 <LI>write your own script and call it with <VAR>leftupdown</VAR> and <VAR>
 471  rightupdown</VAR>. </LI>
 472 </UL>
 473 <P> We provide an <A href="#exupdownchains">example script</A> for use
 474  with ipchains(8) below.</P>
 475 <H3><A name="dhr">DHR on the updown script</A></H3>
 476 <P> Here are some mailing list comments from <A href="manpage.d/ipsec_pluto.8.html">
 477 pluto(8)</A> developer Hugh Redelmeier on an earlier draft of this
 478 document:</P>
 479 <PRE>
 480 There are many important things left out
 481
 482 - firewalling is important but must reflect (implement) policy.  Since
 483   policy isn't the same for all our customers, and we're not experts,
 484   we should concentrate on FW and MASQ interactions with FreeS/WAN.
 485
 486 - we need a diagram to show packet flow WITHIN ONE MACHINE, assuming
 487   IKE, IPsec, FW, and MASQ are all done on that machine.  The flow is
 488   obvious if the components are run on different machines (trace the
 489   cables).
 490
 491   IKE input:
 492         + packet appears on public IF, as UDP port 500
 493         + input firewalling rules are applied (may discard)
 494         + Pluto sees the packet.
 495
 496   IKE output:
 497         + Pluto generates the packet &amp; writes to public IF, UDP port 500
 498         + output firewalling rules are applied (may discard)
 499         + packet sent out public IF
 500
 501   IPsec input, with encapsulated packet, outer destination of this host:
 502         + packet appears on public IF, protocol 50 or 51.  If this
 503           packet is the result of decapsulation, it will appear
 504           instead on the paired ipsec IF.
 505         + input firewalling rules are applied (but packet is opaque)
 506         + KLIPS decapsulates it, writes result to paired ipsec IF
 507         + input firewalling rules are applied to resulting packet
 508           as input on ipsec IF
 509         + if the destination of the packet is this machine, the
 510           packet is passed on to the appropriate protocol handler.
 511           If the original packet was encapsulated more than once
 512           and the new outer destination is this machine, that
 513           handler will be KLIPS.
 514         + otherwise:
 515           * routing is done for the resulting packet.  This may well
 516             direct it into KLIPS for encoding or encrypting.  What
 517             happens then is described elsewhere.
 518           * forwarding firewalling rules are applied
 519           * output firewalling rules are applied
 520           * the packet is sent where routing specified
 521
 522  IPsec input, with encapsulated packet, outer destination of another host:
 523         + packet appears on some IF, protocol 50 or 51
 524         + input firewalling rules are applied (but packet is opaque)
 525         + routing selects where to send the packet
 526         + forwarding firewalling rules are applied (but packet is opaque)
 527         + packet forwarded, still encapsulated
 528
 529   IPsec output, from this host or from a client:
 530         + if from a client, input firewalling rules are applied as the
 531           packet arrives on the private IF
 532         + routing directs the packet to an ipsec IF (this is how the
 533           system decides KLIPS processing is required)
 534         + if from a client, forwarding firewalling rules are applied
 535         + KLIPS eroute mechanism matches the source and destination
 536           to registered eroutes, yielding a SPI group.  This dictates
 537           processing, and where the resulting packet is to be sent
 538           (the destinations SG and the nexthop).
 539         + output firewalling is not applied to the resulting
 540           encapsulated packet
 541
 542 - Until quite recently, KLIPS would double encapsulate packets that
 543   didn't strictly need to be.  Firewalling should be prepared for
 544   those packets showing up as ESP and AH protocol input packets on
 545   an ipsec IF.
 546
 547 - MASQ processing seems to be done as if it were part of the
 548   forwarding firewall processing (this should be verified).
 549
 550 - If a firewall is being used, it is likely the case that it needs to
 551   be adjusted whenever IPsec SAs are added or removed.  Pluto invokes
 552   a script to do this (and to adjust routing) at suitable times.  The
 553   default script is only suitable for ipfwadm-managed firewalls.  Under
 554   LINUX 2.2.x kernels, ipchains can be managed by ipfwadm (emulation),
 555   but ipchains more powerful if manipulated using the ipchains command.
 556   In this case, a custom updown script must be used.
 557
 558   We think that the flexibility of ipchains precludes us supplying an
 559   updown script that would be widely appropriate.
 560 </PRE>
 561  We do provide a sample script in the next section. It is essentially a
 562 transliteration of the version we supply for ipfwadm. Because it
 563 doesn't process the command line argument, it cannot be directly
 564 subsituted -- it won't support the semantics of *firewall=no. It can be
 565 used in <VAR>[left|right]updown=</VAR>.
 566 <H3><A name="exupdownchains">Example updown script for ipchains</A></H3>
 567 <P> Here is an example updown script for use with ipchains. It is
 568 intended to be called via an <VAR>updown=</VAR> statement in <A href="manpage.d/ipsec.conf.5.html">
 569  ipsec.conf</A>. </P>
 570 <PRE>
 571 #! /bin/sh
 572 # sample updown script for ipchains
 573 # Copyright (C) 2000  D. Hugh Redelmeier, Henry Spencer
 574 #
 575 # This program is free software; you can redistribute it and/or modify it
 576 # under the terms of the GNU General Public License as published by the
 577 # Free Software Foundation; either version 2 of the License, or (at your
 578 # option) any later version.  See .
 579 #
 580 # This program is distributed in the hope that it will be useful, but
 581 # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 582 # or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 583 # for more details.
 584 #
 585 # RCSID $Id: firewall.html,v 1.20 2001/06/12 05:14:54 sandy Exp $
 586
 587 # check interface version
 588 case &quot;$PLUTO_VERSION&quot; in
 589 1.0)    ;;
 590 *)      echo &quot;$0: unknown interface version \`$PLUTO_VERSION'&quot; &gt;2        exit 2
 591         ;;
 592 esac
 593
 594 # check parameter(s)
 595 case &quot;$*&quot; in
 596 '')     ;;
 597 *)      echo &quot;$0: parameters unexpected&quot; &gt;2        exit 2
 598         ;;
 599 esac
 600
 601 # utility functions for route manipulation
 602 # Meddling with this stuff should never be necessary and is most unwise.
 603 uproute() {
 604         route add -net $PLUTO_PEER_CLIENT_NET netmask $PLUTO_PEER_CLIENT_MASK \
 605                 dev $PLUTO_INTERFACE gw $PLUTO_NEXT_HOP
 606 }
 607 downroute() {
 608         route del -net $PLUTO_PEER_CLIENT_NET netmask $PLUTO_PEER_CLIENT_MASK \
 609                 dev $PLUTO_INTERFACE gw $PLUTO_NEXT_HOP
 610 }
 611
 612 # the big choice
 613 case &quot;$PLUTO_VERB&quot; in
 614 prepare-host|prepare-client)
 615         # delete possibly-existing route (preliminary to adding a route)
 616         oops=&quot;`route del -net $PLUTO_PEER_CLIENT_NET \
 617                                         netmask $PLUTO_PEER_CLIENT_MASK 2&gt;1&quot;
 618         status=&quot;$?&quot;
 619         if test &quot; $oops&quot; = &quot; &quot; -a &quot; $status&quot; != &quot; 0&quot;
 620         then
 621                 oops=&quot;silent error in route command, exit status $status&quot;
 622         fi
 623         case &quot;$oops&quot; in
 624         'SIOCDELRT: No such process')
 625                 # This is what route (currently -- not documented!) gives
 626                 # for &quot;could not find such a route&quot;.
 627                 status=0
 628                 ;;
 629         esac
 630         exit $status
 631         ;;
 632 route-host|route-client)
 633         # connection to this host or client being routed
 634         uproute
 635         ;;
 636 unroute-host|unroute-client)
 637         # connection to this host or client being unrouted
 638         downroute
 639         ;;
 640 up-host)
 641         # connection to this host coming up
 642         ;;
 643 down-host)
 644         # connection to this host going down
 645         ;;
 646 up-client)
 647         # connection to client subnet, through forwarding firewall, coming up
 648         ipchains -I forward -j ACCEPT -b \
 649                 -s $PLUTO_MY_CLIENT_NET/$PLUTO_MY_CLIENT_MASK \
 650                 -d $PLUTO_PEER_CLIENT_NET/$PLUTO_PEER_CLIENT_MASK
 651         ;;
 652 down-client)
 653         # connection to client subnet, through forwarding firewall, going down
 654         ipchains -D forward -j ACCEPT -b \
 655                 -s $PLUTO_MY_CLIENT_NET/$PLUTO_MY_CLIENT_MASK \
 656                 -d $PLUTO_PEER_CLIENT_NET/$PLUTO_PEER_CLIENT_MASK
 657         ;;
 658 *)      echo &quot;$0: unknown verb \`$PLUTO_VERB' or parameter \`$1'&quot; &gt;2        exit 1
 659         ;;
 660 esac</PRE>
 661 <H2><A name="examplefw">Ipchains firewall configuration at boot</A></H2>
 662 <P> It is also possible to set up both firewalling and IPSEC with
 663 appropriate scripts at boot and then not use <VAR>leftupdown=</VAR> and <VAR>
 664 rightupdown=</VAR>, or use them only for simple up and down operations.</P>
 665 <P> Basically, the technique is </P>
 666 <UL>
 667 <LI>allow IPSEC packets (typically, IKE on UDP port 500 plus ESP,
 668 protocol 50)
 669 <UL>
 670 <LI>incoming, if the destination address is your gateway (and
 671 optionally, only from known senders) </LI>
 672 <LI>outgoing, with the from address of your gateway (and optionally,
 673 only to known receivers) </LI>
 674 </UL>
 675 </LI>
 676 <LI>let <A href="glossary.html#Pluto">Pluto</A> deal with IKE </LI>
 677 <LI>let <A href="glossary.html#KLIPS">KLIPS</A> deal with ESP </LI>
 678 <LI>if necessary, filter incoming packets emerging from KLIPS. </LI>
 679 </UL>
 680 <P> Firewall rules can recognise packets emerging from IPSEC. They are
 681 marked as arriving on an interface such as <VAR>ipsec0</VAR>, rather
 682 than <VAR>eth0</VAR>, <VAR>ppp0</VAR> or whatever. </P>
 683 <P> While it is possible to create such rules yourself (please let us
 684 know via the <A href="mail.html">mailing list</A> if you do), it may be
 685 both easier and more secure to use a set which has already been
 686 published and tested. Those we know of are described below. </P>
 687 <H3><A name="Ranch.trinity">Scripts based on Ranch's work</A></H3>
 688 <P> One user, Rob Hutton, posted his boot time scripts to the mailing
 689 list, and we included them in previous versions of this documentation.
 690 They are still available from our <A href="http://www.freeswan.org/freeswan_trees/freeswan-1.5/doc/firewall.html#examplefw">
 691 web site</A>. However, they were for an earlier FreeS/WAN version so we
 692 no longer recommend them. Also, they had some bugs. See this <A href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/04/msg00316.html">
 693 message</A>. </P>
 694 <P> Those scripts were based on David Ranch's scripts for his &quot;Trinity
 695 OS&quot; for setting up a secure Linux. Check his <A href="http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html">
 696 home page</A> for the latest version and for information on his <A href="biblio.html#ranch">
 697 book</A> on securing Linux. If you are going to base your firewalling
 698 on Ranch's scripts, we recommend using his latest version, and sending
 699 him any IPSEC modifications you make for incorporation into later
 700 versions.</P>
 701 <H3><A name="seawall">The Seattle firewall</A></H3>
 702  We have had several mailing lists reports of good results using
 703 FreeS/WAN with Seawall (the Seattle Firewall). See that project's <A href="http://seawall.sourceforge.net/">
 704 home page</A> on Sourceforge.
 705 <H3><A name="rcf">The RCF scripts</A></H3>
 706  Another set of firewall scripts with IPSEC support are the RCF or
 707 rc.firewall scripts. See their <A href="http://jsmoriss.mvlan.net/linux/rcf.html">
 708 home page</A>. <HR>
 709 <A HREF="toc.html">Contents</a>
 710 <A HREF="manpages.html">Previous</a>
 711 <A HREF="trouble.html">Next</a>
 712 </BODY>
 713 </HTML>