1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
4 <TITLE> Introduction to FreeS/WAN</TITLE>
5 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
8 <A HREF="toc.html">Contents</a>
9 <A HREF="install.html">Previous</a>
10 <A HREF="manpages.html">Next</a>
12 <H1><A name="setup">Configuration</A></H1>
13 <P>This section describes setting up and testing Linux FreeS/WAN.</P>
14 <P>Before attempting this, you should:</P>
16 <LI>look at our <A href="intro.html">introduction</A> section. We
17 assume here that you understand concepts and terms described there.</LI>
18 <LI>ensure that FreeS/WAN is installed on your system. See these links:
20 <LI><A href="install.html#testinstall">testing</A> whether FreeS/WAN is
22 <LI>performing an <A href="install.html">installation</A></LI>
26 <P> You also need to set up and test IP networking on all the machines
27 you plan to install FreeS/WAN on or to use in testing, before trying to
28 set up FreeS/WAN. This is discussed in more detail after the
29 description of our example networks.</P>
30 <H2><A name="example">Our example networks</A></H2>
31 <P> For our examples, we assume that there are only three networks
32 involved, two that want to talk to each other plus the Internet in the
33 middle. The idea is to build an encrypted tunnel across the Internet so
34 the two networks can talk securely. Once you have this working between
35 two network gateways, extending it to three or more is straightforward.</P>
36 <P> In our examples, we'll call the two gateways East and West. We'll
37 have only one client machine on each net: Sunrise in the East and
38 Sunset in the West.</P>
41 Sunset==========West------------------East=========Sunrise
42 local net untrusted net local net
44 <P> Our goal here is to tell you how to set up the two gateways, East
45 and West. We assume your goal is to ensure that East and West encrypt
46 all traffic between them, or at least all that your security policies
47 require them to encrypt.</P>
48 <P> Of course one does not always have a security gateway separate from
49 the client machine. Especially for road warriors, a network that looks
50 like this is common:</P>
53 corporate LAN traveller's laptop
54 Sunset==========West------------------East
55 local net untrusted net
57 <P>and this is possible:</P>
59 West------------------East
62 <P> In our configuration files, and in this discussion, we treat the
63 two simpler setups as degenerate cases of the network-to-network link.
64 For all the diagrams above, for example, we speak of "the subnet behind
65 East". In two of the diagrams, of course, that "subnet" is just the
67 <P> This may take some getting used to, but we hope it is less
68 confusing than continually having to say things like "the subnet behind
69 East (or the East machine itself if there is no client subnet)".</P>
70 <H2><A name="testnet">Configuration for a testbed network</A></H2>
71 <P>Many users just want to get IPSEC installed on a few machines. They
72 can skip this section.</P>
73 <P>Others may want to build a testbed network, for any of a number of
74 reasons. For them, we have some suggestions.</P>
75 <P> The ideal test setup for IPSEC is something like:</P>
77 Sunset==========West-----eth0 eth1-----East=========Sunrise
78 local net test machine local net
80 <P> The test machine routes packets between the two gateways. This
81 makes things more complicated than if you just connected the two
82 gateway machines directly to each other, but it also makes your test
83 setup much more like the environment you actually use IPSEC in. Those
84 environments nearly always involve routing, and quite a few apparent
85 IPSEC failures turn out to be problems with routing or with firewalls
86 dropping packets. This approach lets you deal with those problems on
88 <P> Also, the test machine is in the ideal position to run diagnostic
89 software (such as tcpdump(8)) for checking IPSEC packets. Such software
90 is likely to misbehave if run on the gateways themselves. It is
91 designed to look into a normal IP stack and may become confused if you
92 ask it to display data from a stack which has IPSEC in play.</P>
93 <P> For more detailed testbed information see these <A href="mail.html">
94 mailing list</A> messages: </P>
96 <LI>a user's detailed <A href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00571.html">
97 setup diary</A> for his testbed network </LI>
98 <LI>a FreeS/WAN team member's <A href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00425.html">
99 notes</A> from testing at an IPSEC interop "bakeoff" </LI>
101 <H2><A name="setupnet">Set up and test networking</A></H2>
102 <P> Before trying to get FreeS/WAN working, you should configure and
103 test IP networking on both gateways and on at least one client machine
104 behind each of them. <STRONG>IPSEC cannot work without a working IP
105 network beneath it.</STRONG> Many reported "FreeS/WAN problems" turn
106 out to actually be problems with routing or firewalling. If any actual
107 IPSEC problems turn up, you often cannot even recognise them (much less
108 debug them) unless the underlying network is right.</P>
109 <P>If you need advice on this, your best sources are likely:</P>
111 <LI>the <A href="http://www.linuxdoc.org/HOWTO/Net-HOWTO/index.html">
112 Networking Howto</A></LI>
113 <LI>the <A href="http://www.linuxdoc.org/LDP/nag2/index.html">Network
114 Administrator's Guide</A>.</LI>
115 <LI>the <A href="http://netfilter.kernelnotes.org/unreliable-guides/networking-concepts-HOWTO/index.html">
116 Linux Networking-concepts HOWTO</A> from Rusty Russell, author of most
117 of the Linux firewalling code</LI>
119 <P> See also our <A href="biblio.html">bibliography</A>. </P>
120 <P>Here is our network diagram again:</P>
122 Sunset==========West------------------East=========Sunrise
123 local net untrusted net local net
125 <P> The client machines, Sunrise and Sunset in our example, may have
126 assigned <A href="glossary.html#routable">routable</A> IP addresses, or
127 they may be using private <A href="glossary.html#non-routable">
128 non-routable</A> addresses (as defined in RFC 1918) with the gateways
129 doing <A href="glossary.html#masq">IP masquerade</A>. It doesn't matter
130 which, as long as whatever it is works correctly.</P>
131 <P>Note, however, that the two subnets must have distinct addresses.
132 You cannot have them both masqueraded to the same range of RFC 1918
135 <LI>If Sunrise and Sunset have routable IP addresses, test that they
136 can ping each other.</LI>
137 <LI>If IP masquerading is in use, test as far as you can. For example,
138 if Sunset is masqueraded behind West then Sunrise cannot ping Sunset
139 but should be able to ping West. Whether Sunset can ping Sunrise,
140 assuming Sunrise is not masqueraded, would depend on whether West's
141 rules let ICMP packets through. If not, you should adjust those rules.</LI>
143 <P>In any case, it is not enough to just test that East and West can
145 <H3><A name="forward">Enabling packet forwarding</A></H3>
146 <P> Some systems turn off packet forwarding by default, even for
147 kernels in which it has been enabled. This is the safe default. You
148 don't want systems forwarding packets in uncontrolled ways. </P>
149 <P> To turn forwarding on temporarily, use the following command as
152 echo "1" > /proc/sys/net/ipv4/ip_forward
154 Turning it on permanently is also possible. The exact method varies
155 from distribution to distribution:
157 <DT>Older Readhat </DT>
158 <DD>in the file <VAR>/etc/sysconfig/network</VAR>, set <VAR>
159 FORWARD_IPV4=yes </VAR></DD>
160 <DT>Redhat 6.x and 7.0 </DT>
161 <DD>in the file <VAR>/etc/sysconfig/network</VAR>, set <VAR>
162 net.ipv4.ip_forward=1 </VAR></DD>
163 <DT>Debian r2.2 systems (and most likely Debian r2.2 derived systems): </DT>
164 <DD>in the file <VAR>/etc/network/options</VAR>, set <VAR>
165 ip_forward=yes </VAR></DD>
167 <P> A gateway machine needs forwarding enabled or it will not route
168 packets between the two networks it is attached to. The simplest way to
169 ensure this is to enable forwarding using whatever method your
170 distribution provides. See list above. </P>
171 <P> A more conservative approach is to disable forwarding in your
172 system configuration, then enable from your boot scripts after
173 appropriate firewall scripts are in place. </P>
174 <H3><A name="othersoft">Other software</A></H3>
175 <P> Configure and test any other software you will want to use for
176 testing once IPSEC is up. For example, you might put an HTTP daemon on
177 Sunset and a browser on Sunrise. Make sure these work without IPSEC.</P>
178 <P>If these tests fail, figure out why and fix it. <STRONG>Do not
179 proceed until it works.</STRONG></P>
180 <H2><A name="rtfm">RTFM (please Read The Fine Manuals)</A></H2>
181 <P> As with most things on any Unix-like system, most parts of Linux
182 FreeS/WAN are documented in online manual pages. We provide a list of <A href="manpages.html">
183 FreeS/WAN man pages</A>, with links to HTML versions of them. </P>
184 <P> The man pages describing configuration files are: </P>
186 <LI><A href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A></LI>
187 <LI><A href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</A></LI>
189 <P> Man pages for commands used in this document include:</P>
191 <LI><A href="manpage.d/ipsec.8.html">ipsec(8)</A></LI>
192 <LI><A href="manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</A></LI>
193 <LI><A href="manpage.d/ipsec_rsasigkey.8.html">ipsec_rsasigkey(8)</A></LI>
194 <LI><A href="manpage.d/ipsec_auto.8.html">ipsec_auto(8)</A></LI>
195 <LI><A href="manpage.d/ipsec_manual.8.html">ipsec_manual(8)</A></LI>
197 <P> You can read these either in HTML using the links above or with the <VAR>
198 man(1)</VAR> command.</P>
200 <H2><A name="usersakey">Setting up RSA authentication keys</A></H2>
201 <P> RSA keys come in matched pairs. Each pair includes:</P>
203 <LI>a <STRONG>public key</STRONG> which need not be kept secure.
204 Everyone you plan to communicate with must be able to get a copy of
205 this. It does not matter if an enemy gets it as well.</LI>
206 <LI>a <STRONG>private key</STRONG> which must be kept secure. No-one
207 but you should have access to it. </LI>
209 <P> For FreeS/WAN, both keys for your system are in the <A href="manpage.d/ipsec.secrets.5.html">
210 ipsec.secrets(5)</A> file. <STRONG>Maintaining security of this file is
211 essential</STRONG> since it holds your private key.</P>
212 <P> Public keys for systems you communicate with are placed in <A href="manpage.d/ipsec.conf.5.html">
213 ipsec.conf(5)</A>. Security here is less vital (unless you are using
214 manual keying as well, in which case the file may have secret keys). It
215 does not matter if an enemy knows the public keys, as long as the
216 private keys are protected.</P>
217 <H3><A name="genrsakey">Generating an RSA key pair</A></H3>
218 <P> If you installed FreeS/WAN yourself, then the installation process
219 has already generated an RSA key pair for you and placed it in the <A href="manpage.d/ipsec.secrets.5.html">
220 ipsec.secrets(5)</A> file.</P>
221 <P>If not, you need to:</P>
223 <LI>Generate an RSA key pair (private and public) using <A href="manpage.d/ipsec_rsasigkey.8.html">
224 ipsec_rsasigkey(8)</A>.</LI>
225 <LI>Put the private key in <A href="manpage.d/ipsec.secrets.5.html">
226 ipsec.secrets</A>, with a wrapper. The result looks like this: </LI>
229 <stuff generated by rsasigkey>
235 <LI>the ":" must be unindented (at the margin)</LI>
236 <LI>the other lines, including the "}", must be indented (not at the
238 <LI>spaces are needed to separate tokens so, for example, ":RSA{"
242 <P> This means "always use this as my private RSA key". For other
243 options, for example if you want to use different keys with different
244 partners, see the man pages.</P>
245 <P> The RSA keys we generate are suitable <STRONG>only</STRONG> for
246 authentication, not for encryption. IPSEC uses them only for
247 authentication. See our <A href="ipsec.html">IPSEC</A> section for
249 <P> It is also possible to use keys in other formats, not generated by
250 FreeS/WAN. This may be necessary for interoperation with other IPSEC
251 implementations. See our links to <A href="web.html#patches">patches</A>
252 which add support for keys generated by PGP or embedded in X.509
254 <H3><A name="keyexchange">Exchanging authentication keys</A></H3>
255 <P> The next step is to send your public key to everyone you need to
256 set up connections with, and collect their public keys. The public key
257 is the line in the output of rsasigkey starting "#pubkey=0x".</P>
258 <P> Public keys need not be protected as fanatically as private keys.
259 They are intended to be made public; the system is designed to work
260 even if an enemy knows all the public keys used.</P>
261 <P> Note, however, that <STRONG>authentication of public keys is
262 critical</STRONG>. It does not matter if an enemy knows your public
263 keys, but if you can be tricked into trusting a public key supplied by
264 an enemy, you are in deep trouble.</P>
265 <P> For example, consider the fellow who wants to communicate with his
266 mistress, keeping messages secret from his wife. </P>
268 <LI>If the wife obtains the mistress' public key, that is not a
269 problem. As long as she does not get the private key, she can neither
270 read things sent to the mistress nor authenticate herself as the
272 <LI>If the mistress has any sense, she protects her private key
273 carefully. So long as she does that, and the husband encrypts his
274 messages correctly, there should be no (cryptographic!) problem.</LI>
275 <LI>However, imagine that the wife is somewhat devious. She generates a
276 public/private key pair and sends the husband that public key, forging
277 the message to look as if it came from the mistress. Of course this
278 fails if the husband has enough sense to check the key's validity
279 before using it.</LI>
280 <LI>However, if the husband blindly <EM>accepts that key without
281 verification</EM>, it is <EM>extremely</EM> unlikely that he will be
282 pleased with the results.</LI>
283 <LI>If he accepts that key, the wife can read every message he sends to
285 <LI>She can also pose as the mistress and send him whatever messages
288 <P> You <STRONG>must authenticate any public keys received</STRONG>
289 before using them. For remote sites, the simplest method is to
290 exchange them using PGP-signed email (taking appropriate steps to
291 authenticate the signing keys). For nearby machines, a floppy disk or
292 trusted network is fine.</P>
293 <H3><A name="useRSA">Using RSA signatures for authentication</A></H3>
294 <P> For each system you will communicate with, you need an RSA public
295 key and an identifier associated with it. The identifiers go in the <VAR>
296 leftid=</VAR> and <VAR>rightid=</VAR> lines of connection descriptions
297 in <VAR>ipsec.conf(5)</VAR>. They are the names the systems use to
298 identify themselves during connection negotiation.</P>
299 <P> There are four possible forms for these identifiers:</P>
301 <LI>an IP address in dotted quad notation, four numbers separated by
302 periods (10.1.19.32).</LI>
303 <LI>a domain name, which will be resolved immediately
304 (bad.example.com).</LI>
305 <LI>a fully qualified domain name (FQDN) with a leading "@" to
306 indicate that it should not be resolved (@good.example.com)</LI>
307 <LI>user@FQDN (fred@example.com)</LI>
309 <P> We recommend that only the @FQDN form be used in most applications.
310 IP addresses make remarkably uninteresting names. Resolving a name to
311 an IP address is not interesting in this context, and attempting to
312 resolve it may cause problems if DNS is down or if someone subverts a
313 DNS server which you rely on. </P>
314 <P> If your domain is example.com, the names you use should be of three
317 <LI>machine names such as "@firewall.example.com".</LI>
318 <LI>names for other resources, chosen not to conflict, such as
319 "@fireplug.example.com"</LI>
320 <LI>identifiers for people (actually for their road warrior machines),
321 such as "@alice.example.com" or, if she prefers,
322 "@cleopatra.example.com".</LI>
324 <P> In order to facilitate distributing keys through DNS, we recommend
327 <LI>names from non-existent domains</LI>
328 <LI>names from other people's domains</LI>
329 <LI>names which conflict with machine names in your domain</LI>
332 <P> For example, if you have a server alice.example.com, then you
333 should not use "@alice.example.com" to identify Alice's laptop for
335 <H2><A name="basic.conf">The configuration file</A></H2>
336 <P>FreeS/WAN uses a configuration file, <A href="manpage.d/ipsec.conf.5.html">
337 ipsec.conf(5)</A>.</P>
338 This section describes setting up the parts of that file that apply to
341 <DT><VAR>config setup</VAR> section</DT>
342 <DD>describes machine configuration</DD>
343 <DT><VAR>conn default</VAR> section</DT>
344 <DD>default parameters which apply to all connections</DD>
346 <P> and gives an introduction to the parts of the file that specify the
347 actual connections. The following section covers setting up three
348 common types of connection, all using automatic keying with RSA
349 authentication of the gateways:</P>
351 <DT>conventional VPN</DT>
352 <DD>two security gateways, each with a known fixed IP address and with
353 a network of client machines behind it</DD>
354 <DT>Road Warrior</DT>
355 <DD>one player has a dynamically-assigned address</DD>
356 <DT>opportunistic encryption</DT>
357 <DD>the two machines have no prior knowledge of each other, but are set
358 up to secure connections whenever possible</DD>
360 <P>Setup is quite similar for each of these, but details differ.</P>
361 <P>Other types of connections are covered in later sections.</P>
362 <P>The easiest way to create a connection is by editing one of our
363 examples. Here we will use the one in the installation <A href="manpage.d/ipsec.conf.5.html">
364 ipsec.conf</A> file. You could also start with one from our <A href="examples">
365 doc/examples</A> file if one of those is closer to what you need to do.</P>
366 <H3><A name="setup.conf">The setup section of ipsec.conf(5)</A></H3>
367 <P>The first section of <A href="manpage.d/ipsec.conf.5.html">
368 ipsec.conf(5)</A> contains overall setup parameters for IPSEC, which
369 apply to all connections. In our example file, it is:</P>
371 # basic configuration
373 # THIS SETTING MUST BE CORRECT or almost nothing will work;
374 # %defaultroute is okay for most simple cases.
375 interfaces=%defaultroute
376 # Debug-logging controls: "none" for (almost) none, "all" for lots.
379 # Use auto= parameters in conn descriptions to control startup actions.
382 # Close down old connection when new one using same ID shows up.
385 <P>The variables set here are:</P>
388 <DD>Tells the <A href="glossary.html#KLIPS">KLIPS</A> IPSEC code in the
389 Linux kernel which network interface to use. The interfaces specified
390 here are the only ones this gateway machine will use to communicate
391 with other IPSEC gateways. <STRONG>If this is not correct, nothing
393 <P>In many cases, the appropriate interface is just your default
394 connection to the world (the Internet, or your corporate network). In
395 these cases, you can use the default setting:</P>
397 <LI>interfaces=%defaultroute</LI>
399 <P> To check what FreeS/WAN sees as the default route, you can use the
400 command <VAR>ipsec showdefaults</VAR>. You may need to compare this
401 with the output from <VAR>route -n</VAR> to get a more complete
403 <P>In other cases, you can name one or more specific interfaces to be
404 used by FreeS/WAN. For example:</P>
406 <LI>interfaces="ipsec0=eth0"</LI>
407 <LI>interfaces="ipsec0=eth0 ipsec1=ppp0"</LI>
409 Both tell KLIPS to use eth0 as ipsec0. The second one also supports
413 <LI>Multiple tunnels do not require multiple interfaces. It is
414 possible, and even common, to have one ipsec interface carrying
415 traffic for many tunnels.</LI>
416 <LI>For PPP connections, you specify the virtual PPP interface (for
417 example <VAR>ppp0</VAR>) here, <STRONG>not</STRONG> the underlying
418 physical interface.</LI>
420 <P>If you need to discover interface names, use the command:</P>
422 If you have PCMCIA or other interfaces that are not available at boot
423 time, special measures are required. See our <A href="#dynamic">section</A>
426 <DD>Debugging setting for the KLIPS kernel code</DD>
428 <DD>Debugging setting for the Pluto key and connection negotiation
430 <P><VAR>klipsdebug</VAR> and <VAR>plutodebug</VAR> can each be set to
431 "none" or to "all" in most circumstances. There are other options; see
432 the relevant man pages.</P>
434 <DD>List of connections to be automatically loaded into memory when
437 <DD>List of connections to be automatically negotiated when Pluto
439 <P><VAR>plutoload</VAR> and <VAR>plutostart</VAR> can be quoted lists
440 of connection names, but are often set to <VAR>%search</VAR> as in our
441 example. Any connection with <VAR>auto=add</VAR> in its connection
442 definition is then loaded, and any connection with <VAR> auto=start</VAR>
444 <P>In most cases, you want <VAR>plutostart=%search</VAR> here and <VAR>
445 auto=start</VAR> in your connection descriptions. That way when a
446 connection is broken, for example if one machine crashes or is taken
447 down for some reason, it will be reliably rebuilt. If only one end is
448 told to start the connection, then if the other end crashes, you may
449 lose the connection for a long time. The end that could rebuild does
450 not know it needs to.</P>
451 <P>The exception to the above is when you have many road warriors
452 connecting to a single gateway. Having the gateway trying to rebuild
453 tunnels to systems which are offline can waste considerable resources.
454 In this case, the gateway should have <VAR>auto=add</VAR> for all
455 connections, and let the remote systems start negotiations.</P>
457 <DD>Controls whether two connections with the same subnet on the
458 remote end are allowed. Normally this is set to <VAR>yes</VAR> so that
459 when a remote system disconnects and reconnects, Pluto will
460 automatically take the old connection down. </DD>
462 <H3><A name="conn.default">Connection defaults</A></H3>
463 <P> There is a special name %default that lets you define things that
464 apply to all connections. e.g. our example file has:</P>
466 # defaults for subsequent connection descriptions
468 # How persistent to be in (re)keying negotiations (0 means very).
470 # How to authenticate gateways
473 <P>Variables set here are:</P>
476 <DD>How persistent to be in (re)keying negotiations (0 means very). </DD>
477 <P>For testing, you might wish to set this to some small number,
478 perhaps even to 1, to avoid wasting resources on incorrectly set up
479 connections. In production, it is often set to zero (retry forever).
480 Keeping the connection up is what machine resources are for, so if a
481 connection is down you night as well waste resources retrying as waste
482 them by sitting idle. Of course some caution should be exercised with
483 this, since it can waste network resources as well.</P>
484 <DT>authby=rsasig</DT>
485 <DD>authenticate gateways using RSA signatures. This is the preferred
486 method and is what we will use in this section's examples. An
487 alternate method is to use <A href="#prodsecrets">shared secrets</A>.</DD>
489 <P>Once you are finished testing, you can edit these defaults, adding
490 anything that is standard for all gateways in your organisation.</P>
491 <P> Previous versions of this document said: <BLOCKQUOTE> Note,
492 however, that setting the <VAR>auto=</VAR> parameter in the default
493 connection description <STRONG>does not work</STRONG>. You cannot use <VAR>
494 auto=start</VAR> here to get all connections started automatically or <VAR>
495 auto=add</VAR> to get them all loaded. You must set that in the
496 individual connection descriptions. </BLOCKQUOTE> This restriction has
497 been removed in FreeS/WAN 1.9. However, if the other end of the tunnel
498 is an older version, the restriction will still apply there, so some
499 caution is still required. </P>
500 <H3><A name="edit.conn">Editing a connection description</A></H3>
501 <P>Edit our example connection to match what you want to do. Rename it
502 appropriately for the connection you would like to build:
503 "fred-susan", "reno-van" or whatever. The name is the second string in
504 the line that begins with "conn", for example in:</P>
508 <P> The connection name is "snt" (<STRONG>s</STRONG>ub<STRONG>n</STRONG>
509 et <STRONG>t</STRONG>unnel) and to define another connection you make a
510 copy with a new name such as:</P>
514 <P> A sample connection description is:</P>
517 # The network here looks like:
518 # leftsubnet====left----leftnexthop......rightnexthop----right====rightsubnet
519 # If left and right are on the same Ethernet, omit leftnexthop and rightnexthop.
521 # left security gateway (public-network address)
523 # next hop to reach right
524 leftnexthop=10.44.55.66
525 # subnet behind left (omit if there is no subnet)
526 leftsubnet=172.16.0.0/24
527 # right s.g., subnet behind it, and next hop to reach left
529 rightnexthop=10.88.77.66
530 rightsubnet=192.168.0.0/24
532 We omit here the variables we have shown as set in the default
533 connection above. All of them could also be set here. If they are set
534 in both places, settings here take precedence. Defaults are used only
535 if the specific connection description has no value set.
536 <P>The network described above looks like this:</P>
538 subnet 172.16.0.0/24 =leftsubnet
540 interface 172.16.0.something
542 interface 10.0.0.1 =left
544 interface 10.44.55.66 =leftnexthop
546 interface we don't know
550 interface we don't know
552 interface 10.88.77.66 =rightnexthop
554 interface 10.12.12.1 =right
555 right gateway machine
556 interface 192.168.0.something
558 subnet 192.168.0.0/24 =rightsubnet</PRE>
559 You need to edit the connection description, inserting appropriate IP
560 addresses and subnet descriptions so that it describes your network.
561 <P>In most cases, you should use numeric IP addresses, not names, here.
562 The file syntax allows names to be used, but this creates an
563 additional risk. If someone can subvert the DNS service, then they can
564 redirect packets whose addresses are looked up via that service.</P>
565 <P> Many of the variables in this file come in pairs such as
566 "leftsubnet: and "rightsubnet", one for each end of the connection. The
567 variables on the left side are:</P>
570 <DD>The gateway's external interface, the one it uses to talk to the
571 other gateway. This can be <VAR>left=%defaultroute</VAR>.</DD>
573 <DD>Where left should send packets whose destination is right,
574 typically the first router in the appropriate direction. </DD>
575 <P>This need not always be set.</P>
577 <LI>If the two gateways are directly linked (packets can go from one
578 to the other without IP routing by any intermediate device) then you
579 need not set either <VAR>leftnexthop</VAR> or <VAR> rightnexthop</VAR>.</LI>
580 <LI>a connection with <VAR>left=%defaultroute</VAR> or <VAR>
581 right=%defaultroute</VAR> must not have the corresponding <VAR> nexthop</VAR>
584 However, <EM>in all other cases</EM>, you <EM>must</EM> provide
585 nexthop information. KLIPS (Kernel IP Security) bypasses the normal
586 routing machinery, so you must give KLIPS the information even though
587 routing already knows it.
588 <P>(Yes, we know that design is not ideal, and we plan to change it.
589 See extensive discussions on the <A href="mail.html">mailing list</A>,
590 mostly with "routing" or "KLIPS 2" in the subject lines.)</P>
592 <DD>Addresses for the machines which left is protecting.
594 <LI>Often something like 101.202.203.0/24 to indicate that a subnet
595 resides behind left. Often this subnet will be directly connected to
596 left, but this not necessary. The only requirement is that left must
597 be able to route to it.</LI>
598 <LI>If you omit the leftsubnet line, then left is both the security
599 gateway and the only client on that end.</LI>
601 For some applications, you may want to create two connections, one to
602 protect traffic from the subnet behind left and another to protect
603 traffic from the left gateway itself. This takes two connection
604 descriptions. See <A href="#multitunnel">below</A>.</DD>
605 <DT>leftfirewall</DT>
606 <DD>Set to "yes" if there is a firewall in play that suppresses
607 forwarding, for example if a subnet behind left uses non-routable
608 addresses and left does <A href="glossary.html#masq">IP masquerade</A>
609 for them. This will cause <A href="manpage.d/ipsec_pluto.8.html">Pluto</A>
610 to invoke our default script to adjust the firewall as required. </DD>
611 <P> For more detail, including ways to invoke your own customised
612 script instead, see our <A href="firewall.html">FreeS/WAN and firewalls</A>
615 <DD>If the <VAR>conn setup</VAR> section has <VAR> plutoload=%search</VAR>
616 , then all connections marked <VAR> auto=add</VAR> are loaded when
618 <P> If the <VAR>conn setup</VAR> section has <VAR> plutostart=%search</VAR>
619 , then all connections marked <VAR> auto=start</VAR> are started when
621 <P> Initially, we suggest using <VAR>auto=add</VAR> on all
622 connections. This lets you start them manually during testing. Once
623 they are tested, you can change many of them to <VAR>auto=start</VAR>. </P>
625 <P>For each left* parameter, there is a corresponding right* parameter.</P>
626 <P>Note that <EM>a connection to a subnet behind left does not include
627 left itself</EM>. The tunnel described above protects packets going <EM>
628 from one subnet to the other</EM>. It does not apply to packets which
629 either begin or end their journey on one of the gateways. If you need
630 to protect those packets, you must build separate tunnel descriptions
632 <P>It is a common error to attempt testing a subnet-to-subnet
633 connection by pinging from one of the gateways to the far end or vice
634 versa. <STRONG>This does not work</STRONG>, even if the connection is
635 functioning perfectly, because <EM>traffic to or from the gateway
636 itself is not sent on that connection</EM>. If you want to protect
637 traffic originating or terminating on the gateway, then you need a
638 separate tunnel for that in addition to the subnet's tunnel. See the
639 section on <A href="#multitunnel">multiple tunnels</A> below.</P>
640 <H3><A name="which">Which is which?</A></H3>
641 <P>Which security gateway is "left" and which is "right" is arbitrary.</P>
642 <P>We suggest that you name connections by their ends. For example,
643 name the link between Fred and Susan's machines "fred-susan" or the
644 link between your Reno and Vancouver offices "reno-van". You can then
645 let "left" refer to the left half of the name, "fred" or "reno" in our
646 examples, and "right" to the other half.</P>
647 <P>To simplify administration, we recommend that you <STRONG>use the
648 same names</STRONG> in the <VAR>ipsec.conf</VAR> files <STRONG>on both
649 ends</STRONG>. The name "reno", for example, should refer to the
650 machine in Reno, no matter which city the file is in, and if "reno" is
651 "left" in the reno-van description in Reno, then "reno" should be
652 "left" in that description on the Vancouver machine as well. </P>
653 <P> Then when you copy the file from one machine to the other, the <EM>
654 only</EM> change you should make on the second machine is changing the <VAR>
655 interfaces=</VAR> line to match the interface that machine uses for
657 <P> Of course the software does not actually require this. The names
658 are just arbitrary strings to it. If your administrator in Reno wants
659 to refer to the machines as "Phobos" and "Demios" while the Vancouver
660 admin calls them "George" and "Gracie", things should still work.</P>
661 <H2><A name="examples">Example setups</A></H2>
662 <P> In this section we show examples of three common setups: </P>
664 <LI>a VPN connection </LI>
665 <LI>road warrior support </LI>
666 <LI>opportunistic encryption </LI>
668 <P> We use a, b, c ... to indicate components of IP addresses. Each
669 letter is some number in the range 0 to 255, inclusive.</P>
670 <P> For additional examples, see our <A href="examples">examples</A>
672 <H3><A name="VPNex">VPN</A></H3>
673 <P> In this example, the network looks like this:</P>
675 subnet a.b.c.0/24 =leftsubnet
676 | (head office has routable IP addresses)
679 interface e.f.g.h =left
680 | (external address outside a.b.c.0 subnet)
681 interface e.f.g.i =leftnexthop
683 interface we don't know
687 interface we don't know
689 interface j.k.l.m =rightnexthop
691 interface j.k.l.n =right
692 right gateway machine
693 interface 192.168.0.something
694 | (branch office uses private IP addresses)
695 subnet 192.168.0.0/24 =rightsubnet
697 <P> The ipsec.conf(5) file might look like this (with RSA keys
698 shortened for easy display):</P>
700 # basic configuration
708 # defaults that apply to all connection descriptions
710 # How persistent to be in (re)keying negotiations (0 means very).
712 # How to authenticate gatways
715 # VPN connection for head office and branch office
717 # identity we use in authentication exchanges
718 leftid=@head.example.com
719 leftrsasigkey=0x175cffc641f...
720 # left security gateway (public-network address)
722 # next hop to reach right
724 # subnet behind left (omit if there is no subnet)
725 leftsubnet=a.b.c.0/24
726 # right s.g., subnet behind it, and next hop to reach left
727 rightid=@branch.example.com
728 rightrsasigkey=0xfc641fd6d9a24...
731 rightsubnet=192.168.0.0/24
732 # right is masquerading
736 <P> The versions of this file at the two ends should be identical,
737 except that each must have an <VAR>interfaces=</VAR> line appropriate
738 for the local machine.</P>
739 <H4><A name="route_or_not">Routable and non-routable addresses</A></H4>
740 <P> RFC 1918 reserves three groups of addresses for use on private
744 <LI>172.16.0.0/12 </LI>
745 <LI>192.168.0.0/16 </LI>
747 <P> Addresses in these ranges will never be assigned to anything on the
748 Internet. Many routers automatically drop any packet with one of these
749 addresses as either source or destination. </P>
750 <P> You can use FreeS/WAN to route between two such networks, using for
751 example <VAR>leftsubnet=192.168.47.0/24</VAR> and <VAR>
752 rightsubnet=192.168.48.0/24</VAR>. These addresses still do not appear
753 on the Internet; they are encapsulated inside IPSEC packets which have
754 the gateways' external addresses (from the <VAR>left</VAR> and <VAR>
755 right</VAR> parameters of the connection description) in their headers. </P>
756 <H3><A name="roadex">Road Warrior</A></H3>
757 <P> For our purposes, a "road warrior" is any machine that does not
758 have a fixed IP address where it can normally be expected to be on
759 line. This includes:</P>
761 <LI>a traveller who might connect from anywhere</LI>
762 <LI>any machine that has a dynamic IP address -- nearly all dialup
763 connections and most DSL or cable modem connections, at least in North
765 <LI>most home machines connecting to the office. If you have a home
766 firewall that is always left on and has a static IP address, then you
767 can use the <A href="#VPNex">VPN</A> configuration described above.
768 Otherwise, consider yourself a road warrior.</LI>
770 <P> The configuration for road warrior support looks slightly different
771 from a VPN configuration. We cannot use the road warrior's IP address
772 in the configuration file since we don't know it, and we don't want to
773 have our server retrying connections to road warriors that are no
775 <P> In this example, the network looks like this:</P>
777 subnet a.b.c.0/24 =leftsubnet
778 | (head office has routable IP addresses)
781 interface e.f.g.h =left
782 | (external address outside a.b.c.0 subnet)
783 interface e.f.g.i =leftnexthop
788 interface with dynamic IP address
791 <P> Here the ipsec.conf(5) files on the two ends are slightly
792 different. The one at the office might have exactly the same <VAR>
793 config setuo</VAR> and <VAR>conn %default</VAR> sections as in the VPN
796 # basic configuration
804 # defaults that apply to all connection descriptions
806 # How persistent to be in (re)keying negotiations (0 means very).
808 # How to authenticate gatways
811 <P> Then add a description for the road warrior connection:</P>
813 # Connection for road warrior Fred
815 # identity we use in authentication exchanges
816 leftid=@head.example.com
817 leftrsasigkey=0x175cffc641f...
818 # left security gateway (public-network address)
820 # next hop to reach right
822 # subnet behind left (omit if there is no subnet)
823 leftsubnet=a.b.c.0/24
824 # accept any address for right
826 # any address, provided authentication works
827 rightid=@fred.example.com
828 rightrsasigkey=0xd9a24765fe...
829 # no subnet for a typical road warrior
830 # it is possible, but usually not needed
831 # let the road warrior start the connection
833 # override the default retry for road warriors
834 # we don't want to retry if IP connectivity is gone
837 <P> On the gateway end we use</P>
839 <LI><VAR>right=%any</VAR> so we have no preset idea of right's IP
840 address and will accept whatever arrives on the packets</LI>
841 <LI><VAR>auto=add</VAR> so we accept connections but don't initiate</LI>
842 <LI><VAR>keyingtries=1</VAR> so we do not retry to excess when the
843 partner disconnects or changes IP address</LI>
845 <P> The file on the road warrior end is nearly identical, except that
848 <LI><VAR>interfaces=%defaultroute</VAR> to handle the dynamic IP
850 <LI><VAR>right=%defaultroute</VAR></LI>
851 <LI><VAR>auto=start</VAR> to start the connection</LI>
852 <LI><VAR>keyingtries=0</VAR> to try to maintain the connection</LI>
854 <P> Additional road warriors can be added as required. Each should have
855 his or her own connection description with unique settings for <VAR>
856 rightid</VAR> and <VAR>rightrsasigkey</VAR>.</P>
857 <P> Jean-Francois Nadeau's <A href="http://jixen.tripod.com/#Rw-Fwan-to-Fwan">
858 Practical Configurations</A> document also has an example of using RSA
859 authentication for road warriors.</P>
860 <H3><A name="oppex">Opportunistic encryption</A></H3>
861 We use the term <A href="glossary.html">opportunistic encryption</A>
862 for encryption which does not rely on any pre-arranged connection,
863 hence does not require that the administrators of the two gateways
864 involved communicate with each other (for example, to exchange keys)
865 before their systems can create a secure connection.
866 <P> The idea is that each gateway check the destinations of outgoing
867 packets, see if an encrypted connection is possible and, if so, take
868 the opportuntity to encrypt. The opportunity will exist whenever the
869 admins on both ends have set their systems up for opportunistic
871 <P> This makes encryption the default behaviour, and could greatly
872 increase the overall security of the Internet if it were widely enough
873 adopted. See our documents: </P>
875 <DT><A href="politics.html">history and politics</A></DT>
876 <DD>for the reasons we want to do this </DD>
877 <DT><A href="ipsec.html#traffic.resist">IPSEC protocols</A></DT>
878 <DD>for discussion of the general principle of encrypting as much as
881 <P> The gateways must be able to authenticate each other for IPSEC to
882 be secure. For opportunistic encryption, we rely on the domain name
883 system, <A href="glossary.html">DNS</A>, to provide the RSA keys needed
884 for this authentication. Note, that currently this is not entirely
885 secure because <STRONG>the DNS mechanism it relies on is not fully
886 secure</STRONG>. Eventually, as <A href="glossary.html#SDNS">secure DNS</A>
887 becomes widely deployed, this will change. </P>
888 <H4><A name="opp.status">Status</A></H4>
889 The team have been working on this for some time, and testing
890 internally. As of late May, 2001 this code is ready for wider testing. <STRONG>
891 We encourage everyone to try it.</STRONG>
892 <P> The main documentation items so far are: </P>
894 <LI>an <A href="opportunism.howto">Opportunism HowTo</A> by Pluto
895 programmer Hugh Redelmeier </LI>
896 <LI>a <A href="opportunism.spec">design document</A> by Hugh and
897 technical lead Henry Spencer. </LI>
899 I am playing catch up. HTML documentation so far is neither complete
900 nor particularly clear, and not all of it has had technical review by
901 the developers, so it may have errors. What I have so far is below.
902 <P> Note that both software and documentation for this are changing
903 quickly. You may want the latest snapshot for opportunism experiments. </P>
904 <P><STRONG> We do not yet recommend this code for production use</STRONG>
905 . You should still protect your critical data with explicitly
906 configured IPSEC tunnels, rather than relying on opportunistic for
907 everything at this stage. </P>
908 <H4><A name="opp.config">ipsec.conf entries for opportunism</A></H4>
909 The relevant lines in the config file might look like this:
911 conn subnet-to-anyone # for our client subnet
912 leftsubnet=10.42.42.0/24 # any single client in our subnet
913 left=%defaultroute # our SG (defaults leftnexthop too)
916 <P> The public key, in our format, must be in a KEY record of the
917 appropriate DNS entry for this to work.</P>
918 <P> Each opportunistic connection supports a single source/destination
919 pair of IP addresses. There is no way to build an opportunistic
920 connection for a larger subnet. Specifying a subnet in the connection
921 description, as in the example above, just means that any host in that
922 subnet may have opportunistic connections.</P>
923 <H4><A name="dns.background">Some DNS background</A></H4>
924 <P> Opportunism requires that the gateway systems be able to fetch
925 public keys, and other IPSEC-related information, from each other's DNS
926 (domain name service) records. </P>
927 <P> DNS is a distributed database that maps names to IP addresses and
928 vice versa. A system named gateway.example.com with IP address
929 10.20.30.40 should have at least two DNS records: </P>
931 <DT>gateway.example.com. IN A 10.20.30.40 </DT>
932 <DD>used to look up the name and get an IP address </DD>
933 <DT>40.30.20.10.in-addr.arpa. IN PTR gateway.example.com. </DT>
934 <DD>used for reverse lookups, looking up an address to get the
935 associated name. Notice that the digits here are in reverse order; the
936 actual address is 10.20.30.40 but we use 40.30.20.10 here. </DD>
938 Some syntactic details are:
940 <LI>the IN indicates that these records are for <STRONG>In</STRONG>
941 ternet addresses </LI>
942 <LI>The final periods in '.com.' and '.arpa.' are required. They
943 indicate the root of the domain name system. </LI>
945 For much more detail, see:
947 <LI><A href="http://www.linuxdoc.org/LDP/nag2/index.html">Linux Network
948 Administrator's Guide</A></LI>
949 <LI>the standard <A href="biblio.html#DNS.book">DNS reference</A> book </LI>
950 <LI><A href="http://www.nominum.com/resources/whitepapers/bind-white-paper.html">
951 BIND overview</A></LI>
952 <LI><A href="http://www.nominum.com/resources/documentation/Bv9ARM.pdf">
953 BIND 9 Administrator's Reference</A></LI>
955 The capitalised strings after IN indicate the type of record. Possible
958 <LI><STRONG>A</STRONG>ddress </LI>
959 <LI><STRONG>P</STRONG>oin<STRONG>T</STRONG>e<STRONG>R</STRONG></LI>
960 <LI><STRONG>C</STRONG>anonical <STRONG>NAME</STRONG>, records to
961 support aliasing, multiple names for one address </LI>
962 <LI><STRONG>MX</STRONG>, used in mail handling </LI>
963 <LI><STRONG>SIG</STRONG>nature, used in <A href="glossary.html#SDNS">
965 <LI><STRONG>KEY</STRONG>, used in <A href="glossary.html#SDNS">secure
967 <LI><STRONG>T</STRONG>e<STRONG>XT</STRONG>, a multi-purpose record type </LI>
969 To set up for opportunistic encryption, you add some KEY and TXT
970 records to your DNS data.
971 <H4><A name="dnskey">Putting IPSEC information in DNS</A></H4>
972 There are two types of DNS record to be added:
974 <LI>each gateway must have a KEY record which other gateways can query
975 to fetch its RSA authentication key </LI>
976 <LI>any client whose communications are to be protected by a gateway
977 must have a TXT record pointing to that machine as an authorised IPSEC
980 <A href="manpage.d/ipsec_showhostkey.8.html"> ipsec_showhostkey(8)</A>
981 provides the key in DNS record format. You will need to put it in the
982 appropriate place in the DNS records.
983 <P> To be more precise, quoting the Opportunism Design document: </P>
985 For reference, the minimum set of DNS records needed to make
986 this all work is either:
988 1. TXT in Destination reverse map, identifying Responder
989 and providing public key.
990 2. KEY in Initiator reverse map, providing public key.
991 3. TXT in Source reverse map, verifying relationship to
996 1. TXT in Destination reverse map, identifying Responder.
997 2. KEY in Responder reverse map, providing public key.
998 3. KEY in Initiator reverse map, providing public key.
999 4. TXT in Source reverse map, verifying relationship to
1002 Slight complications ensue for dynamic addresses, lack of
1003 control over reverse maps, etc.
1005 <H5><A name="dns.client">DNS records for client systems</A></H5>
1006 You must have control of the reverse maps for your client systems, or
1007 opportunistic IPSEC cannot be made to work.
1008 <P> The client systems will be either Source or Destination, so they
1011 1. TXT in Destination reverse map, identifying Responder
1012 and providing public key.
1014 3. TXT in Source reverse map, verifying relationship to
1019 1. TXT in Destination reverse map, identifying Responder.
1022 4. TXT in Source reverse map, verifying relationship to
1025 If you control the gateway's reverse map, example client records would
1028 42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
1029 42.42.42.10.in-addr.arpa. IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"
1031 which can also be written as just:
1033 42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
1034 IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"
1036 This provides the IP address of the security gateway and the public
1037 key which the gateway will use to authenticate itself. This is the
1039 <H5><A name="dns.gateway">DNS records for gateway systems</A></H5>
1040 The gateways will be either Initiator or Responder so they need:
1043 2. KEY in Initiator reverse map, providing public key.
1049 2. KEY in Responder reverse map, providing public key.
1050 3. KEY in Initiator reverse map, providing public key.
1053 <P> If you control the gateway's reverse map, you just add a KEY record
1054 there. That is all the gateway reverse map needs, whether it is working
1055 as Initiator or Responder. </P>
1056 <P> Here is an example, with many characters of the key itself left
1059 40.30.20.10.in-addr.arpa. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8
1061 This allows lookups on the IP address of the gateway to retrieve the
1063 <H6>If you <EM>don't</EM> control the gateway's reverse map</H6>
1064 The approach must be different if you do not have control over the
1065 reverse map for your gateway. Perhaps your ISP controls that, and
1066 provides no way for you to put data into their maps. Without that, you
1067 cannot set your gateway up to respond to incoming opportunistic
1068 requests (short of changing ISPs, which you might consider).
1069 <P> However, suppose a friend over at example.org will let you put
1070 things in their maps. That will allow you to set your gateway up to
1071 handle opportunistic connections for which it is the initiator. </P>
1072 <P> You still need to be able to put data in the reverse map for your
1073 clients. However, that data is slightly different: </P>
1075 42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
1076 IN TXT "X-IPsec-Server(10)=something.example.org"
1078 Over at example.org, your friend puts these lines in the DNS data
1081 something.example.org. IN A 10.20.30.40
1082 something.example.org. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8
1084 Your gateway must identify itself in IKE as something.example.org, not
1085 as gateway.example.com. You set that up via <VAR>leftid=</VAR> or <VAR>
1086 rightid=</VAR> entries in <A href="manpage.d/ipsec.conf.5.html">
1088 <P> With this arrangement, the remote gateway receives an ID payload
1089 early in IKE with your (bogus) gateway name "something.example.org".
1090 Then it looks up that name to get the IP address and key for the
1092 <H2><A name="handy">Simplifying ipsec.conf files</A></H2>
1093 <P> We provide several features in the syntax of the <A href="manpage.d/ipsec.conf.5.html">
1094 ipsec.conf(5)</A> file that are intended to simplify the work of
1095 managing complex multi-connection setups:</P>
1097 <LI>a <VAR>conn %default</VAR> connection description for information
1098 common to all connections</LI>
1099 <LI><VAR>also=</VAR> lines allow a piece of a description to be defined
1100 in one place and used in several (the definition must be after all
1102 <LI><VAR>include</VAR> directives allow information to be stored in
1103 separate files but used as part of the configuration</LI>
1105 <P> These can be combined in whatever way suits your application. One
1106 example is this ipsec.conf file for a gateway supporting multiple road
1107 warriors, all using RSA authentication:</P>
1113 authby=rsasig # all connections use RSA authentication
1114 keyingtries=1 # road warrior can retry, we shouldn't
1115 # some parameters are common to all remote systems
1116 right=%any # accept from any address
1118 # pick up all remote system descriptions
1119 # uses shell wildcards
1120 include /etc/ipsec/remote.*.conn
1122 # left side of all connections is the same
1123 # define it after the descriptions which use it
1125 left=101.101.101.101
1126 leftnexthop=101.101.101.1
1127 leftsubnet=202.202.202.0/24
1128 leftid=@gateway.example.org
1130 <P> On the left gateway, we can omit <VAR>leftrsasig</VAR>. That
1131 gateway uses the private key stored in ipsec.secrets(5) and has no need
1132 for its own public key. Similarly, the road warriors need not have
1133 their own public keys in ipsec.conf(5), only the gateway's public key. </P>
1134 <P> The remote connection descriptions in <VAR>/etc/ipsec/remote.*.conn</VAR>
1135 need then have only a few lines each: </P>
1138 # pick up common info for all connections
1140 # identify the remote machine
1141 rightid=@myname.example.org
1142 rightrsasigkey=0xfc641fd6d9a24...
1143 # we cannot use auto= in default or an also= section
1145 auto=add # load, but don't start
1147 <P> Note that if <VAR>auto=add</VAR> or <VAR>auto=start</VAR>
1148 parameters are used, they <STRONG>must be in the actual connection
1149 descriptions</STRONG>. Neither putting them in the <VAR>conn default</VAR>
1150 section nor including them via an <VAR>also=</VAR> line will work.</P>
1151 <P> Also, be careful with the order of sections in this file. The
1152 parser used requires that a definition comes after the <VAR>also=</VAR>
1153 line which uses it. In our example, the <VAR>include</VAR> inserts the
1154 files with the <VAR>also=leftstuff</VAR> lines before the definition of <VAR>
1155 conn leftstuff</VAR> so things are parsed in the correct order.</P>
1156 <H2><A name="fw.basic">Is there a firewall in play?</A></H2>
1157 <P> If firewall packet filtering is being done on either of the
1158 FreeS/WAN gateway machines, or on any machine on the path between them,
1159 then you will probably need to adjust the filters before FreeS/WAN can
1160 work. The filters must allow:</P>
1162 <LI>UDP packets between port 500 on one gate and port 500 on the other,
1163 used by the automatic keying daemon Pluto.</LI>
1164 <LI>at least one of protocol 50 (ESP) and 51 (AH). Most applications
1165 want ESP since AH does only authentication, not encryption.</LI>
1167 <P> For more detail, see our <A href="firewall.html">IPSEC and firewalls</A>
1169 <H2><A name="testing">Testing the installation</A></H2>
1170 <P> This section covers testing connections once you have FreeS/WAN
1171 installed and your <A href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A>
1173 <P> We assume all your connection descriptions use <VAR>auto=add</VAR>
1174 so that <A href="manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</A>
1175 loads the descriptions into its internal database at startup but does
1176 not attempt to start the connections until you tell it to.</P>
1177 <H3><A name="matching">Matching numbers</A></H3>
1178 <P> It is important that the numbers in your connection descriptions
1179 match the network configuration. FreeS/WAN is almost certain to fail if
1181 <P> Suppose you are at the Reno office and your ipsec.conf file now
1182 has, among others, these lines:</P>
1185 interfaces="ipsec0=eth0"
1188 left=101.101.101.101
1189 right=202.202.202.202
1191 <P> When you tell FreeS/WAN to start the reno-van connection, it
1192 doesn't automagically know that it is in Reno, or that it is <VAR>left</VAR>
1193 in the configuration. It discovers that by comparing the IP address
1194 for ipsec0 (and, if it is set, for ipsec1) to the addresses for left
1195 and right. ipsec0 inherits its address from the underlying device, eth0
1197 <P> So in our example, if eth0 has IP address 101.101.101.101 then
1198 ipsec0 inherits that address, the correct match is found, and this
1199 FreeS/WAN discovers that it is <VAR>left</VAR>. (If no match is found, <A
1200 href="manpage.d/ipsec_pluto.8.html">Pluto</A> reports "unable to orient
1201 connection".) It then sets itself up with any other left* parameters
1202 in use -- some of <VAR>leftnexthop</VAR>, <VAR>leftsubnet</VAR>, <VAR>
1203 leftfirewall</VAR> and <VAR>leftid</VAR>. </P>
1204 <P> Once it has these parameters, FreeS/WAN sets things so that </P>
1206 <LI>packets from leftsubnet addressed to rightsubnet are routed through
1207 a tunnel to right.</LI>
1208 <LI>Packets for leftsubnet can be received on the tunnel and delivered.</LI>
1210 <P> All should be well.</P>
1211 <P> Of course, there must also be interfaces and routes set up so that
1212 this machine can exchange IP packets both with the right gateway and
1213 with clients on leftsubnet. This is done with standard Linux utilities
1214 such as ifconfig(8) and route(8). Also, things must be correct on right
1215 in Vancouver. It takes two to tunnel.</P>
1216 <P> A data mismatch anywhere in this configuration will cause FreeS/WAN
1217 to fail and to log various error messages. Depending on just how
1218 confused FreeS/WAN is and about what, the error messages may be
1219 somewhat confusing. See our <A href="trouble.html">troubleshooting</A>
1220 section to get help interpreting them if required.</P>
1221 <P><EM> We recommend double-checking for consistency here before
1222 starting actual tests.</EM>.</P>
1223 <H3><A name="testsetup">Sanity checking</A></H3>
1224 <P> Reboot both gateways to get FreeS/WAN started. No connections are
1225 actually made yet, but the stage is set.</P>
1226 <P> Examine /var/log/messages for any signs of trouble.</P>
1227 <P> On both gateways, the following entries should now exist in the
1228 /proc/net/ directory:</P>
1230 <LI>ipsec_eroute</LI>
1232 <LI>ipsec_spigrp</LI>
1233 <LI>ipsec_spinew</LI>
1234 <LI>ipsec_tncfg</LI>
1235 <LI>ipsec_version</LI>
1237 <P> and the IPSEC interfaces should be attached on top of the specified
1238 physical interfaces. Confirm that with:</P>
1240 cat /proc/net/ipsec_tncfg
1242 <P> You should see at least device ipsec0, and each ipsec device should
1243 point to a physical device, eg. 'ipsec0 -> eth0 mtu=16260 -> 1500'.
1244 Routing connections through this pseudo-device with our eroute(8)
1245 utility causes the data to be encrypted before being delivered to the
1246 underlying network interface.</P>
1247 <P> Don't be surprised when you cannot find that /dev/ipsec0 or
1248 /dev/ipsec1. They do not exist. Other network pseudo-devices such as
1249 eth0 and eth1 do not have entries in /dev either. In general, network
1250 devices do not need such entries.</P>
1251 <H3><A name="test">Starting a connection</A></H3>
1252 <P> On one gateway, start IPSEC with:</P>
1254 ipsec auto --up <VAR>name</VAR>
1256 <P> replacing <VAR>name</VAR> with the connection name you used in
1258 <P> Note that to shut down a connection, you must do:</P>
1260 ipsec auto --down <VAR>name</VAR>
1262 <P> on <EM>both</EM> gateway machines, even though you only start it
1264 <P> If the <VAR>ipsec auto --up</VAR> command doesn't generate any
1269 <P> and see if the output looks something like this:</P>
1271 foo.spsystems.net Wed Nov 25 22:51:45 EST 1998
1272 -------------------------
1273 10.0.1.0/24 -> 11.0.1.0/24 => tun0x200@11.0.0.1 esp0x202@11.0.0.1
1274 -------------------------
1275 tun0x200@11.0.0.1 IPv4_Encapsulation: dir=out 10.0.0.1 -> 11.0.0.1
1276 esp0x203@10.0.0.1 3DES-MD5-96_Encryption: dir=in iv=0xc2cbca5ba42ffbb6 seq=0 bit=0x00000000 win=0 flags=0x0<>
1277 esp0x202@11.0.0.1 3DES-MD5-96_Encryption: dir=out iv=0xc2cbca5ba42ffbb6 seq=0 bit=0x00000000 win=0 flags=0x0<>
1278 Destination Gateway Genmask Flags MSS Window irtt Iface
1279 11.0.0.0 0.0.0.0 255.255.255.0 U 1500 0 0 eth1
1280 11.0.1.0 11.0.0.1 255.255.255.0 UG 1404 0 0 ipsec0</PRE>
1281 <P> If it does, you're probably in business.</P>
1282 <P> This example shows:</P>
1284 a tunnel tun0x200 going to 11.0.0.1
1285 outgoing connection esp0x202
1286 incoming connection esp0x203
1288 <P> Both connections use <A href="glossary.html#ESP">ESP</A> with <A href="glossary.html#3DES">
1289 3DES</A> encryption and <A href="glossary.html#MD5">MD5</A>
1291 <P> The routing is:</P>
1293 11.0.0.0 via eth1 and the Internet
1294 11.0.1.0 via ipsec0 which encrypts and then sends to 11.0.0.1
1296 <P> This routes all traffic to the protected network 11.0.1.0/24
1297 through an IPSEC tunnel to the gateway 11.0.0.1.</P>
1298 <H3><A name="pingtest">Ping tests</A></H3>
1299 <P> If that works, test whether Sunrise can ping Sunset and vice versa.
1300 Our example setup again is:</P>
1302 Sunset==========West------------------East=========Sunrise
1303 local net untrusted net local net
1305 <P> There is no point in testing to or from the gateways themselves;
1306 the goal is to secure traffic between the subnets, not between the
1307 security gateways themselves.</P>
1308 <P> In general, pings or other <STRONG>tests using the public
1309 interfaces of East and/or West are entirely useless</STRONG>. The IPSEC
1310 tunnel is for packets between the two protected subnets and the outside
1311 interfaces are not on those subnets. Depending on your routing
1312 configuration, test packets sent via those interfaces will be:</P>
1314 <LI>either transmitted in the clear, bypassing the tunnel,</LI>
1315 <LI>or discarded because there is no tunnel in place to handle them</LI>
1317 <P> In either case, <STRONG>they tell you nothing about the tunnel</STRONG>
1319 <P> Sometimes it will be inconvenient to use the client machines
1320 (Sunrise and Sunset in our example) for testing. In these cases, use a
1321 command such as:</P>
1323 traceroute -i eth0 -f 20 192.168.7.1
1325 <P> where each of the interfaces specified (eth0 and 192.168.7.1 in the
1326 example) are <STRONG>on one of the protected subnets</STRONG>, eth0
1327 being the local gateway's interface on that side and 192.168.7.1 the
1328 remote gateway's subnet interface. This forces the packets through the
1329 IPSEC tunnel you want to test.</P>
1330 <P> For information on setting things up so that gateways can do IPSEC
1331 to each other or to remote subnets, see <A href="#multitunnel">below</A>
1333 <P>If you have other software set up, test with it as well. Telnet from
1334 Sunrise to Sunset, browse a web server on the remote net and so on.</P>
1335 <H3><A name="tcpdump">Testing with tcpdump</A></H3>
1336 <P> To verify that all is working, run tcpdump(8) on a machine which
1337 can listen to the traffic between the gateways.</P>
1338 <P> This is most easily done from a third machine, rather than from one
1339 of the gateways. On the gateways you may see packets at intermediate
1340 stages of processing and the result may be confusing. </P>
1341 <P> If the results make no sense at all, or you see "bad physical
1342 medium" error messages, you probably have an outdated version of
1343 tcpdump(8) that does not handle IPSEC at all. See our <A href="faq.html#tcpdump">
1345 <P> The packets should, except for some of the header information, be
1346 utterly unintelligible. The output of good encryption looks exactly
1347 like random noise.</P>
1348 <P>You can put recognizable data in the ping packets with something
1350 <PRE> ping -p feedfacedeadbeef 11.0.1.1</PRE>
1351 <P> "feedfacedeadbeef" is a legal hexadecimal pattern that is easy to
1352 pick out of hex dumps.</P>
1353 <P> For many other protocols, you need to check if you have encrypted
1354 data or ASCII text. Encrypted data has approximately equal frequencies
1355 for all 256 possible characters. ASCII text has most characters in the
1356 printable range 0x20-0x7f, a few control characters less than 0x20, and
1357 none at all in the range 0x80-0xff.</P>
1358 <P> 0x20, space, is a good character to look for. In normal English
1359 text space occurs about once in seven characters, versus about once in
1360 256 for random or encrypted data. You can put long sequences of spaces
1361 in your data and look for 0x20202020 in output, but this is not usually
1363 <P> If packets look like total garbage, nothing recognizable, all is
1365 <P>Note that to shut down a connection, you must do:</P>
1366 <PRE> ipsec auto --down <VAR>name</VAR></PRE>
1367 <P>on <EM>both</EM> gateway machines, even though you only start it
1369 <P>Again, you can verify with the same commands.</P>
1370 <P>Repeat the ping test. Repeat the tcpdump test.</P>
1371 <P>If everything succeeds, congratulations.</P>
1372 <P><STRONG>You now have a working Linux FreeS/WAN installation.</STRONG></P>
1373 <H2><A name="links.conf">What next?</A></H2>
1374 <P> At this point you should have a working FreeS/WAN setup. If not,
1375 you could go back and doublecheck various things above or try:</P>
1378 <LI>our <A href="faq.html">FAQ</A></LI>
1379 <LI>our <A href="trouble.html">troubleshooting</A> section</LI>
1381 <P> If all is well so far, you could continue with this section to
1382 explore other ways to configure FreeS/WAN connections or branch out to:</P>
1384 <LI>more detail on the <A href="ipsec.html">IPSEC protocols</A></LI>
1385 <LI><A href="interop.html">interoperating</A> with other IPSEC
1386 implementations</LI>
1387 <LI><A href="politics.html">history and politics of cryptography</A></LI>
1388 <LI>additional <A href="examples">configuration examples</A></LI>
1390 <P> Of course you might just go off for a beverage or meal at this
1392 <H2><A name="otherconf">Other configuration possibilities</A></H2>
1393 <P> The rest of this section describes various less-used options for
1395 <H3><A name="choose">Choosing connection types</A></H3>
1396 <P> The first major decision you need to make before configuring
1397 additional connections is what type or types of connections you will
1398 use. There are several options, and you can use more than one
1400 <H4><A name="man-auto">Manual vs. automatic keying</A></H4>
1401 <P> IPSEC allows two types of connections, with manual or automatic
1402 keying. FreeS/WAN starts them with commands such as:</P>
1404 ipsec manual --start <VAR>name</VAR>
1405 ipsec auto --up <VAR>name</VAR>
1407 <P>The difference is in how they are keyed.</P>
1409 <DT><A href="glossary.html#manual">Manually keyed</A> connections</DT>
1410 <DD>use keys stored in <A href="manpage.d/ipsec.conf.5.html">ipsec.conf</A>
1412 <DT><A href="glossary.html#auto">Automatically keyed</A> connections</DT>
1413 <DD>use keys automatically generated by the Pluto key negotiation
1414 daemon. The key negotiation protocol, <A href="glossary.html#IKE">IKE</A>
1415 , must authenticate the other system. (It is vulnerable to a <A href="glossary.html#middle">
1416 man-in-the-middle attack</A> if used without authentication.) We
1417 currently support two authentication methods:
1419 <LI>using shared secrets stored in <A href="manpage.d/ipsec.secrets.5.html">
1420 ipsec.secrets</A>.</LI>
1421 <LI>RSA <A href="glossary.html#public">public key</A> authentication,
1422 with public keys for other machines in <A href="manpage.d/ipsec.conf.5.html">
1423 ipsec.conf</A> and our machine's private key in <A href="manpage.d/ipsec.secrets.5.html">
1424 ipsec.secrets</A>.</LI>
1428 <P><A href="glossary.html#manual"> Manually keyed</A> connections
1429 provide weaker security than <A href="glossary.html#auto">automatically
1430 keyed</A> connections. An opponent who gets a key gets all data
1431 encrypted by it. We discuss using <A href="#prodman">manual keying in
1432 production</A> below, but this is <STRONG>not recommended</STRONG>
1433 except in special circumstances, such as needing to communicate with
1434 some implementation that offers no auto-keyed mode compatible with
1435 FreeS/WAN. Manual keying is useful for testing.</P>
1436 <P> With automatically-(re)-keyed connections, the keys change often so
1437 an opponent who gets one key does not get a large amount of data. An
1438 opponent who gets a shared secret, or your private key if public key
1439 authentication is used, does not automatically gain access to any
1440 encryption keys or any data. Once your authentication mechanism has
1441 been subverted you have no way to prevent the attacker getting keys and
1442 data, but the attacker still has to work for them.</P>
1443 <H4><A name="auto-auth">Authentication methods for auto-keying</A></H4>
1444 <P> The IKE protocol which Pluto uses to negotiate connections between
1445 gateways must use some form of authentication of peers. A gateway must
1446 know who it is talking to before it can create a secure connection. We
1447 currently support two methods for this authentication:</P>
1449 <LI>shared secrets</LI>
1450 <LI>RSA authentication</LI>
1452 <P> See our <A href="web.html#patch">links section</A> for information
1453 on user-contributed patches which provide a third mechanism:</P>
1455 <LI>authentication with <A href="glossary.html#x509">x.509</A>
1458 <P> As a long-term goal, FreeS/WAN plans to support distribution of
1459 public keys for authentication via <A href="glossary.html#SDNS">secure
1460 DNS</A>. This would allow us to support <A href="glossary.html#carpediem">
1461 opportunistic encryption</A>. Any two FreeS/WAN gateways could provide
1462 secure communication, without either of them having any preset
1463 information about the other.</P>
1464 <P>This is <STRONG>not implemented in this release</STRONG>.</P>
1465 <H4><A name="adv-pk">Advantages of public key methods</A></H4>
1466 <P> Authentication with a <A href="glossary.html#public">public key</A>
1467 method such as <A href="glossary.html#RSA">RSA</A> has some important
1468 advantages over using shared secrets.</P>
1470 <LI>no problem of secure transmission of secrets
1472 <LI>A shared secret must be shared, so you have the problem of
1473 transmitting it securely to the other party. If you get this wrong,
1474 you have no security.</LI>
1475 <LI>With a public key technique, you transmit only your public key.
1476 The system is designed to ensure that it does not matter if an enemy
1477 obtains public keys. The private key never leaves your machine.</LI>
1480 <LI>easier management
1482 <LI>Suppose you have 20 branch offices all connecting to one gateway at
1483 head office, and all using shared secrets. Then the head office admin
1484 has 20 secrets to manage. Each of them must be kept secret not only
1485 from outsiders, but also from 19 of the branch office admins. The
1486 branch office admins have only one secret each to manage.</LI>
1487 <P> If the branch offices need to talk to each other, this becomes
1488 problematic. You need another <NOBR>20*19/2 = 190</NOBR> secrets for
1489 branch-to-branch communication, each known to exactly two branches.
1490 Now all the branch admins have the headache of handling 20 keys, each
1491 shared with exactly one other branch or with head office. </P>
1492 <P> For larger numbers of branches, the number of connections and
1493 secrets increases quadratically and managing them becomes a
1494 nightmare. A 1000-gateway fully connected network needs 499,500
1495 secrets, each known to exactly two players. There are ways to reduce
1496 this problem, for example by introducing a central key server, but
1497 these involve additional communication overheads, more administrative
1498 work, and new threats that must be carefully guarded against.</P>
1501 <LI>With public key techniques, the <EM>only</EM> thing you have to
1502 keep secret is your private key, and <EM>you keep that secret from
1503 everyone</EM>. </LI>
1504 <P> As network size increaes, the number of public keys used increases
1505 linearly with the number of nodes. This still requires careful
1506 administration in large applications, but is nothing like the disaster
1507 of a quadratic increase. On a 1000-gateway network, you have 1000
1508 private keys, each of which must be kept secure on one machine, and
1509 1000 public keys which must be distributed. This is not a trivial
1510 problem, but it is manageable. </P>
1512 <LI>does not require fixed IP addresses
1514 <LI>When shared secrets are used in IPSEC, the responder must be able
1515 to tell which secret to use by looking at the IP address on the
1516 incoming packets. When the other parties do not have a fixed IP
1517 address to be identified by (for example, on nearly all dialup ISP
1518 connections and many cable or ADSL links), this does not work well --
1519 all must share the same secret!</LI>
1520 <LI>When RSA authentication is in use, the initiator can identify
1521 itself by name before the key must be determined. The responder then
1522 checks that the message is signed with the public key corresponding to
1526 <P>There is also a disadvantage:</P>
1528 <LI>your private key is a single point of attack, extremely valuable to
1531 <LI>with shared secrets, an attacker who steals your ipsec.secrets
1532 file can impersonate you or try <A href="glossary.html#middle">
1533 man-in-the-middle</A> attacks, but can only attack connections
1534 described in that file</LI>
1535 <LI>an attacker who steals your private key gains the chance to attack
1536 not only existing connections <EM>but also any future connections</EM>
1537 created using that key</LI>
1541 <P>This is partly counterbalanced by the fact that the key is never
1542 transmitted and remains under your control at all times. It is likely
1543 necessary, however, to take account of this in setting security
1544 policy. For example, you should change gateway keys when an
1545 administrator leaves the company, and should change them periodically
1547 <P> Overall, public key methods are <STRONG>more secure, more easily
1548 managed and more flexible</STRONG>. We recommend that they be used for
1549 all connections, unless there is a compelling reason to do otherwise.</P>
1550 <H3><A name="prodsecrets">Using shared secrets in production</A></H3>
1551 <P> Generally, public key methods are preferred for reasons given
1552 above, but shared secrets can be used with no loss of security, just
1553 more work and perhaps more need to take precautions.</P>
1554 <H4><A name="secrets">Putting secrets in ipsec.secrets(5)</A></H4>
1555 <P> If shared secrets are to be used to <A href="glossary.html#authentication">
1556 authenticate</A> communication for the <A href="glossary.html#DH">
1557 Diffie-Hellman</A> key exchange in the <A href="glossary.html#IKE">IKE</A>
1558 protocol, then those secrets must be stored in <VAR>/etc/ipsec.secrets</VAR>
1559 . For details, see the <A href="manpage.d/ipsec.secrets.5.html">
1560 ipsec.secrets(5)</A> man page.</P>
1561 <P>A few considerations are vital:</P>
1563 <LI>make the secrets long and unguessable. Since they need not be
1564 remembered by humans, very long ugly strings may be used. We suggest
1565 using our <A href="manpage.d/ipsec_ranbits.8.html">ipsec_ranbits(8)</A>
1566 utility to generate long (128 bits or more) random strings.</LI>
1567 <LI>transmit secrets securely. You have to share them with other
1568 systems, but you lose if they are intercepted and used against you.
1569 Use <A href="glossary.html#PGP">PGP</A>, <A href="glossary.html#SSH">SSH</A>
1570 , hand delivery of a floppy disk which is then destroyed, or some
1571 other trustworthy method to deliver them.</LI>
1572 <LI>store secrets securely, in root-owned files with permissions
1574 <LI>limit sharing of secrets. Alice, Bob, Carol and Dave may all talk
1575 to each other, but only Alice and Bob should know the secret for an
1576 Alice-Bob link.</LI>
1577 <LI><STRONG>do not share private keys</STRONG>. The private key for RSA
1578 authentication of your system is stored in <A href="manpage.d#ipsec.secrets.5.html">
1579 ipsec.secrets(5)</A>, but it is a different class of secret from the
1580 pre-shared keys used for the "shared secret" authentication. No-one
1581 but you should have the RSA private key. </LI>
1583 <P> Each line has the IP addresses of the two gateways plus the secret.
1584 It should look something like this:</P>
1586 10.0.0.1 11.0.0.1 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"
1588 <P><VAR> PSK</VAR> indicates the use of a <STRONG>p</STRONG>re-<STRONG>s</STRONG>
1589 hared <STRONG> k</STRONG>ey. The quotes and the whitespace shown are
1591 <P> You can use any character string as your secret. For security, it
1592 should be both long and extremely hard to guess. We provide a utility
1593 to generate such strings, <A href="manpage.d/ipsec_ranbits.8.html">
1594 ipsec_ranbits(8)</A>. </P>
1595 <P> You want the same secret on the two gateways used, so you create a
1596 line with that secret and the two gateway IP addresses. The
1597 installation process supplies an example secret, useful <EM>only</EM>
1598 for testing. You must change it for production use.</P>
1599 <H4><A name="securing.secrets">File security</A></H4>
1600 <P> You must deliver this file, or the relevant part of it, to the
1601 other gateway machine by some <STRONG>secure</STRONG> means. <EM>Don't
1602 just FTP or mail the file!</EM> It is vital that the secrets in it
1603 remain secret. An attacker who knew those could easily have <EM>all the
1604 data on your "secure" connection</EM>.</P>
1605 <P> This file must be owned by root and should have permissions <VAR>
1606 rw-------</VAR>.</P>
1607 <H4><A name="notroadshared">Shared secrets for road warriors</A></H4>
1608 <P> You can use a shared secret to support a single road warrior
1609 connecting to your gateway, and this is a reasonable thing to do in
1610 some circumstances. Public key methods have advantages, discussed <A href="#choose">
1611 above</A>, but they are not critical in this case.</P>
1612 <P> To do this, the line in ipsec.secrets(5) is something like: </P>
1614 10.0.0.1 0.0.0.0 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"
1616 where the <VAR>0.0.0.0</VAR> means that any IP address is acceptable.
1617 <P><STRONG> For more than one road warrior, shared secrets are <EM>not</EM>
1618 recommended.</STRONG> If shared secrets are used, then when the
1619 responder needs to look up the secret, all it knows about the sender is
1620 an IP address. This is fine if the sender is at a fixed IP address
1621 specified in the config file. It is also fine if only one road warrior
1622 uses the wildcard <VAR>0.0.0.0</VAR> address. However, if you have more
1623 than one road warrior using shared secret authentication, then they
1624 must all use that wildcard and therefore <STRONG>all road warriors
1625 using PSK autentication must use the same secret</STRONG>. Obviously,
1626 this is insecure. </P>
1627 <P><STRONG> For multiple road warriors, use public key authentication.</STRONG>
1628 Each roadwarrior can then have its own identity (our <VAR>leftid=</VAR>
1629 or <VAR>rightid=</VAR> parameters), its own public/private key pair,
1630 and its own secure connection. </P>
1631 <H3><A name="prodman">Using manual keying in production</A></H3>
1632 <P> Generally, <A href="glossary.html#auto">automatic keying</A> is
1633 preferred over <A href="glossary.html#manual">manual keying</A> for
1634 production use because it is both easier to manage and more secure.
1635 Automatic keying frees the admin from much of the burden of managing
1636 keys securely, and can provide <A href="glossary.html#PFS">perfect
1637 forward secrecy</A>.</P>
1638 <P> However, it is possible to use manual keying in production if that
1639 is what you want to do. This might be necessary, for example, in order
1640 to interoperate with some device that either does not provide automatic
1641 keying or provides it in some version we cannot talk to.</P>
1642 <P> Note that with manual keying <STRONG>all security rests with the
1643 keys</STRONG>. If an adversary acquires your keys, you've had it. He or
1644 she can read everything ever sent with those keys, including old
1645 messages he or she may have archived. You need to <STRONG>be really
1646 paranoid about keys</STRONG> if you're going to rely on manual keying
1647 for anything important.</P>
1649 <LI>keep keys in files with 600 permissions, owned by root</LI>
1650 <LI>be extremely careful about security of your gateway systems.
1651 Anyone who breaks into a gateway and gains root privileges can get
1652 all your keys and read everything ever encrypted with those keys, both
1653 old messages he has archived and any new ones you may send. </LI>
1654 <LI>change keys regularly. This can be a considerable bother, (and
1655 provides an excellent reason to consider automatic keying instead),
1656 but it is <EM>absolutely essential</EM> for security. Consider a
1657 manually keyed system in which you leave the same key in place for
1660 <LI>an attacker can have a very large sample of text sent with that
1661 key to work with. This makes various cryptographic attacks much more
1662 likely to succeed. </LI>
1663 <LI>The chances of the key being compromised in some non-cryptographic
1664 manner -- a spy finds it on a discarded notepad, someone breaks into
1665 your server or your building and steals it, a staff member is bribed,
1666 tricked, seduced or coerced into revealing it, etc. -- also increase
1668 <LI>a successful attacker can read everything ever sent with that key.
1669 This makes any successful attack extremely damaging. </LI>
1671 It is clear that you must change keys often to have any useful
1672 security. The only question is how often. </LI>
1673 <LI>use <A href="glossary.html#PGP">PGP</A> or <A href="glossary.html#SSH">
1674 SSH</A> for all key transfers</LI>
1675 <LI>don't edit files with keys in them when someone can look over your
1677 <LI>worry about network security; could someone get keys by snooping
1678 packets on the LAN between your X desktop and the gateway?</LI>
1679 <LI>lock up your backup tapes for the gateway system</LI>
1680 <LI>... and so on</LI>
1682 <P> Linux FreeS/WAN provides some facilities to help with this. In
1683 particular, it is good policy to <STRONG>keep keys in separate files</STRONG>
1684 so you can edit configuration information in /etc/ipsec.conf without
1685 exposing keys to "shoulder surfers" or network snoops. We support this
1686 with the <VAR>also=</VAR> and <VAR>include</VAR> syntax in <A href="manpage.d/ipsec_conf.5.html">
1687 ipsec.conf(5)</A>.</P>
1688 <P> See the last example in our <A href="examples">examples</A> file.
1689 In the /etc/ipsec.conf <VAR>conn samplesep</VAR> section, it has the
1694 <P> which tells the "ipsec manual" script to insert the configuration
1695 description labelled "samplesep-keys" if it can find it. The
1696 /etc/ipsec.conf file must also have a line such as:</P>
1698 include ipsec.*.conf
1700 <P> which tells it to read other files. One of those other files then
1701 might contain the additional data:</P>
1706 espenckey=0x01234567_89abcdef_02468ace_13579bdf_12345678_9abcdef0
1707 espauthkey=0x12345678_9abcdef0_2468ace0_13579bdf
1709 <P> The first line matches the label in the "also=" line, so the
1710 indented lines are inserted. The net effect is exactly as if the
1711 inserted lines had occurred in the original file in place of the
1712 "also=" line.</P>
1713 <P>Variables set here are:</P>
1716 <DD>A number needed by the manual keying code. Any 3-digit hex number
1717 will do, but if you have more than one manual connection then <STRONG>
1718 spi must be different</STRONG> for each connection.</DD>
1720 <DD>Options for <A href="glossary.html#ESP">ESP</A> (Encapsulated
1721 Security Payload), the usual IPSEC encryption mode. Settings here are
1722 for <A href="glossary.html#encryption">encryption</A> using <A href="glossary.html#3DES">
1723 triple DES</A> and <A href="glossary.html#authentication">authentication</A>
1724 using <A href="glossary.html#MD5">MD5</A>. Note that encryption
1725 without authentication should not be used; it is insecure.</DD>
1727 <DD>Key for ESP encryption. Here, a 192-bit hex number for triple DES.</DD>
1729 <DD>Key for ESP authentication. Here, a 128-bit hex number for MD5. </DD>
1731 <P><STRONG> Note</STRONG> that the <STRONG>example keys we supply</STRONG>
1732 are intended <STRONG>only for testing</STRONG>. For real use, you
1733 should go to automatic keying. If that is not possible, create your own
1734 keys for manual mode and keep them secret </P>
1735 <P>Of course, any files containing keys <STRONG>must</STRONG> have 600
1736 permissions and be owned by root.</P>
1737 <P> If you connect in this way to multiple sites, we recommend that you
1738 keep keys for each site in a separate file and adopt some naming
1739 convention that lets you pick them all up with a single "include"
1740 line. This minimizes the risk of losing several keys to one error or
1741 attack and of accidentally giving another site admin keys which he or
1742 she has no business knowing.</P>
1743 <P>Also note that if you have multiple manually keyed connections on a
1744 single machine, then the <VAR>spi</VAR> parameter must be different
1745 for each one. Any 3-digit hex number is OK, provided they are
1746 different for each connection. We reserve the range 0x100 to 0xfff for
1747 manual connections. Pluto assigns SPIs from 0x1000 up for
1748 automatically keyed connections.</P>
1749 <P>If <A href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A> contains
1750 keys for manual mode connections, then it too must have permissions <VAR>
1751 rw-------</VAR>. We recommend instead that, if you must manual keying
1752 in production, you keep the keys in separate files.</P>
1753 <P> Note also that <A href="manpage.d/ipsec.conf.5.html">ipsec.conf</A>
1754 is installed with permissions <VAR>rw-r--r--</VAR>. If you plan to use
1755 manually keyed connections for anything more than initial testing, you <B>
1758 <LI>either change permissions to <VAR>rw-------</VAR></LI>
1759 <LI>or store keys separately in secure files and access them via
1760 include statements in <A href="manpage.d/ipsec.conf.5.html">ipsec.conf</A>
1763 <P> We recommend the latter method for all but the simplest
1766 <H4><A name="ranbits">Creating keys with ranbits</A></H4>
1767 <P>You can create new <A href="glossary.html#random">random</A> keys
1768 with the <A href="manpage.d/ipsec_ranbits.8.html">ranbits(8)</A>
1769 utility. For example, the commands:</P>
1771 ipsec ranbits 192 > temp
1772 ipsec ranbits 128 >> temp</PRE>
1773 <P>create keys in the sizes needed for our default algorithms:</P>
1775 <LI>192-bit key for <A href="glossary.html#3DES">3DES</A> encryption
1776 <BR> (only 168 bits are used; parity bits are ignored)</LI>
1777 <LI>128-bit key for keyed <A href="glossary.html#MD5">MD5</A>
1780 <P>If you want to use <A href="glossary.html#SHA">SHA</A> instead of <A href="glossary.html#MD5">
1781 MD5</A>, that requires a 160-bit key</P>
1782 <P>Note that any <STRONG>temporary files</STRONG> used must be kept <STRONG>
1783 secure</STRONG> since they contain keys. That is the reason for the
1784 umask command above. The temporary file should be deleted as soon as
1785 you are done with it. You may also want to change the umask back to
1786 its default value after you are finished working on keys.</P>
1787 <P>The ranbits utility may pause for a few seconds if not enough
1788 entropy is available immediately. See ipsec_ranbits(8) and random(4)
1789 for details. You may wish to provide some activity to feed entropy
1790 into the system. For example, you might move the mouse around, type
1791 random characters, or do <VAR> du /usr > /dev/null</VAR> in the
1793 <H3><A name="boot">Setting up connections at boot time</A></H3>
1794 <P>You can tell the system to set up connections automatically at boot
1795 time by putting suitable stuff in /etc/ipsec.conf on both systems. The
1796 relevant section of the file is labelled by a line reading <VAR>config
1798 <P>Details can be found in the <A href="manpage.d/ipsec.conf.5.html">
1799 ipsec.conf(5)</A> man page. We also provide a file of <A href="examples">
1800 example configurations</A>.</P>
1801 <P>The most likely options are something like:</P>
1804 <DT>interfaces="ipsec0=eth0 ipsec1=ppp0"</DT>
1805 <DD>Tells KLIPS which interfaces to use. Up to four interfaces numbered
1806 ipsec[0-3] are supported. Each interface can support an arbitrary
1807 number of tunnels. </DD>
1808 <P>Note that for PPP, you give the ppp[0-9] device name here, not the
1809 underlying device such as modem (or eth1 if you are using PPPoE).</P>
1810 <DT>interfaces=%defaultroute</DT>
1811 <DD>Alternative setting, useful in simple cases. KLIPS will pick up
1812 both its interface and the next hop information from the settings of
1813 the Linux default route.</DD>
1814 <DT>forwardcontrol=no</DT>
1815 <DD>Normally "no". Set to "yes" if the IP forwarding option is disabled
1816 in your network configuration. (This can be set as a kernel
1817 configuration option or later. e.g. on Redhat, it's in
1818 /etc/sysconfig/network and on SuSE you can adjust it with Yast.) Linux
1819 FreeS/WAN will then enable forwarding when starting up and turn it off
1820 when going down. This is used to ensure that no packets will be
1821 forwarded before IPSEC comes up and takes control.</DD>
1822 <DT>syslog=daemon.error</DT>
1823 <DD>Used in messages to the system logging daemon (syslogd) to specify
1824 what type of software is sending the messages. If the settings are
1825 "daemon.error" as in our example, then syslogd treats the messages as
1826 error messages from a daemon. </DD>
1827 <P>Note that <A href="glossary.html#Pluto">Pluto</A> does not currently
1828 pay attention to this variable. The variable controls setup messages
1830 <DT>klipsdebug=</DT>
1831 <DD>Debug settings for <A href="glossary.html#KLIPS">KLIPS</A>.</DD>
1832 <DT>plutodebug=</DT>
1833 <DD>Debug settings for <A href="glossary.html#Pluto">Pluto</A>.</DD>
1834 <DT>... for both the above DEBUG settings</DT>
1835 <DD>Normally, leave empty as shown above for no debugging output.
1836 <BR> Use "all" for maximum information.
1837 <BR> See ipsec_klipsdebug(8) and ipsec_pluto(8) man page for other
1838 options. Beware that if you set /etc/ipsec.conf to enable debug
1839 output, your system's log files may get large quickly.</DD>
1840 <DT>dumpdir=/safe/directory</DT>
1841 <DD>Normally, programs started by ipsec setup don't crash. If they do,
1842 by default, no core dump will be produced because such dumps would
1843 contain secrets. If you find you need to debug such crashes, you can
1844 set dumpdir to the name of a directory in which to collect the core
1846 <DT>manualstart=</DT>
1847 <DD>List of manually keyed connections to be automatically started at
1848 boot time. Useful for testing, but not for long term use. Connections
1849 which are automatically started should also be automatically re-keyed.</DD>
1851 <DD>Whether to start <A href="glossary.html#Pluto">Pluto</A> when ipsec
1853 <BR> This parameter is optional and defaults to "yes" if not present. </DD>
1854 <P>"yes" is strongly recommended for production use so that the keying
1855 daemon (Pluto) will automatically re-key the connections regularly.
1856 The ipsec-auto parameters ikelifetime, ipseclifetime and reykeywindow
1857 give you control over frequency of rekeying.</P>
1858 <DT>plutoload="reno-van reno-adam reno-nyc"</DT>
1859 <DD>List of tunnels (by name, e.g. fred-susan or reno-van in our
1860 examples) to be loaded into Pluto's internal database at startup. In
1861 this example, Pluto loads three tunnels into its database when it is
1863 <P>If plutoload is "%search", Pluto will load any connections whose
1864 description includes "auto=add" or "auto=start".</P>
1865 <DT>plutostart="reno-van reno-adam reno-nyc"</DT>
1866 <DD>List of tunnels to attempt to negotiate when Pluto is started. </DD>
1867 <P>If plutostart is "%search", Pluto will start any connections whose
1868 description includes "auto=start".</P>
1869 <P>Note that, for a connection intended to be permanent, <STRONG>both
1870 gateways should be set try to start</STRONG> the tunnel. This allows
1871 quick recovery if either gateway is rebooted or has its IPSEC
1872 restarted. If only one gateway is set to start the tunnel and the
1873 other gateway restarts, the tunnel may not be rebuilt.</P>
1874 <DT>plutowait=no</DT>
1875 <DD>Controls whether Pluto waits for one tunnel to be established
1876 before starting to negotiate the next. You might set this to "yes"
1878 <LI>if your gateway is a very limited machine and you need to conserve
1880 <LI>for debugging; the logs are clearer if only one connection is
1881 brought up at a time</LI>
1883 For a busy and resource-laden production gateway, you likely want "no"
1884 so that connections are brought up in parallel and the whole process
1885 takes less time.</DD>
1887 <P>The example assumes you are at the Reno office and will use IPSEC to
1888 Vancouver, New York City and Amsterdam.</P>
1889 <H3><A name="multitunnel">Multiple tunnels between the same two gateways</A>
1891 <P>Consider a pair of subnets, each with a security gateway, connected
1892 via the Internet:</P>
1894 192.168.100.0/24 left subnet
1898 101.101.101.101 left
1900 101.101.101.1 left next hop
1902 202.202.202.1 right next hop
1904 202.202.202.202 right
1908 192.168.200.0/24 right subnet
1910 <P>A tunnel specification such as:</P>
1912 conn northnet-southnet
1913 left=101.101.101.101
1914 leftnexthop=101.101.101.1
1915 leftsubnet=192.168.100.0/24
1917 right=202.202.202.202
1918 rightnexthop=202.202.202.1
1919 rightsubnet=192.168.200.0/24
1922 will allow machines on the two subnets to talk to each other. You
1923 might test this by pinging from polarbear (192.168.100.7) to penguin
1925 <P> However, <STRONG>this does not cover other traffic you might want
1926 to secure</STRONG>. To handle all the possibilities, you might also
1927 want these connection descriptions:</P>
1929 conn northgate-southnet
1930 left=101.101.101.101
1931 leftnexthop=101.101.101.1
1932 right=202.202.202.202
1933 rightnexthop=202.202.202.1
1934 rightsubnet=192.168.200.0/24
1937 conn northnet-southgate
1938 left=101.101.101.101
1939 leftnexthop=101.101.101.1
1940 leftsubnet=192.168.100.0/24
1942 right=202.202.202.202
1943 rightnexthop=202.202.202.1
1945 <P> Without these, neither gateway can do IPSEC to the remote subnet.
1946 There is no IPSEC tunnel or eroute set up for the traffic.</P>
1947 <P> In our example, with the non-routable 192.168.* addresses used,
1948 packets would simply be discarded. In a different configuration, with
1949 routable addresses for the remote subnet, <STRONG>they would be sent
1950 unencrypted</STRONG> since there would be no IPSEC eroute and there
1951 would be a normal IP route.</P>
1952 <P> You might also want:</P>
1954 conn northgate-southgate
1955 left=101.101.101.101
1956 leftnexthop=101.101.101.1
1957 right=202.202.202.202
1958 rightnexthop=202.202.202.1
1960 <P> This is required if you want the two gateways to speak IPSEC to
1962 <P> This requires a lot of duplication of details. Judicious use of <VAR>
1963 also=</VAR> and <VAR>include</VAR> can reduce this problem.</P>
1964 <P> Note that, while FreeS/WAN supports all four tunnel types, not all
1965 implementations do. In particular, some versions of Windows 2000 and
1966 the freely downloadable version of PGP provide only "client"
1967 functionality. You cannot use them as gateways with a subnet behind
1968 them. To get that functionality, you must upgrade to Windows 2000
1969 server or the commercially available PGP products. </P>
1970 <H4><A name="advroute">One tunnel plus advanced routing</A></H4>
1971 It is also possible to use the new routing features in 2.2 and later
1972 kernels to avoid most needs for multple tunnels. Here is one mailing
1973 list message on the topic:
1975 Subject: Re: linux-ipsec: IPSec packets not entering tunnel?
1976 Date: Mon, 20 Nov 2000
1977 From: Justin Guyett <jfg@sonicity.com>
1979 On Mon, 20 Nov 2000, Claudia Schmeing wrote:
1982 > "home" "office"
1983 > 10.92.10.0/24 ---- 24.93.85.110 ========= 216.175.164.91 ---- 10.91.10.24/24
1985 > I've created all four tunnels, and can ping to test each of them,
1986 > *except* homegate-officenet.
1988 I keep wondering why people create all four tunnels. Why not route
1989 traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2?
1990 And 99% of the time you don't need to access "office" directly, which
1991 means you can eliminate all but the subnet<->subnet connection.
1993 and FreeS/WAN technical lead Henry Spencer's comment:
1995 > I keep wondering why people create all four tunnels. Why not route
1996 > traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2?
1998 This is feasible, given some iproute2 attention to source addresses, but
1999 it isn't something we've documented yet... (partly because we're still
2000 making some attempt to support 2.0.xx kernels, which can't do this, but
2001 mostly because we haven't caught up with it yet).
2003 > And 99% of the time you don't need to access "office" directly, which
2004 > means you can eliminate all but the subnet<->subnet connection.
2006 Correct in principle, but people will keep trying to ping to or from the
2007 gateways during testing, and sometimes they want to run services on the
2008 gateway machines too.
2011 <H3><A name="biggate">Many tunnels from a single gateway</A></H3>
2012 <P> FreeS/WAN allows a single gateway machine to build tunnels to many
2013 others. There may, however, be some problems for large numbers as
2014 indicated in this message from the mailing list:</P>
2016 Subject: Re: Maximum number of ipsec tunnels?
2017 Date: Tue, 18 Apr 2000
2018 From: "John S. Denker" <jsd@research.att.com>
2020 Christopher Ferris wrote:
2022 >> What are the maximum number ipsec tunnels FreeS/WAN can handle??
2024 Henry Spencer wrote:
2026 >There is no particular limit. Some of the setup procedures currently
2027 >scale poorly to large numbers of connections, but there are (clumsy)
2028 >workarounds for that now, and proper fixes are coming.
2030 1) "Large" numbers means anything over 50 or so. I routinely run boxes
2031 with about 200 tunnels. Once you get more than 50 or so, you need to worry
2032 about several scalability issues:
2034 a) You need to put a "-" sign in syslogd.conf, and rotate the logs daily
2037 b) Processor load per tunnel is small unless the tunnel is not up, in which
2038 case a new half-key gets generated every 90 seconds, which can add up if
2039 you've got a lot of down tunnels.
2041 c) There's other bits of lore you need when running a large number of
2042 tunnels. For instance, systematically keeping the .conf file free of
2043 conflicts requires tools that aren't shipped with the standard freeswan
2046 d) The pluto startup behavior is quadratic. With 200 tunnels, this eats up
2047 several minutes at every restart. I'm told fixes are coming soon.
2049 2) Other than item (1b), the CPU load depends mainly on the size of the
2050 pipe attached, not on the number of tunnels.
2052 <P> It is worth noting that item (1b) applies only to repeated attempts
2053 to re-key a data connection (IPSEC SA, Phase 2) over an established
2054 keying connection (ISAKMP SA, Phase 1). There are two ways to reduce
2055 this overhead using settings in <A href="manpage.d#ipsec.conf.5.html">
2056 ipsec.conf(5)</A>: </P>
2058 <LI>set <VAR>keyingtries</VAR> to some small value to limit repetitions </LI>
2059 <LI>set <VAR>keylife</VAR> to a short time so that a failing data
2060 connection will be cleaned up when the keying connection is reset. </LI>
2062 <P> The overheads for establishing keying connections (ISAKMP SAs,
2063 Phase 1) are lower because for these Pluto does not perform expensive
2064 operations before receiving a reply from the peer.</P>
2065 <H3><A name="extruded">Extruded Subnets</A></H3>
2066 <P>What we call <A href="glossary.html#extruded">extruded subnets</A>
2067 are a special case of <A href="web.html#VPN">VPNs</A>.</P>
2068 <P>If your buddy has some unused IP addresses, in his subnet far off at
2069 the other side of the Internet, he can loan them to you... provided
2070 that the connection between you and him is fast enough to carry all
2071 the traffic between your machines and the rest of the Internet. In
2072 effect, he "extrudes" a part of his address space over the network to
2073 you, with your Internet traffic appearing to originate from behind his
2074 Internet gateway.</P>
2075 <P>Suppose your friend has a.b.c.0/24 and wants to give you
2076 a.b.c.240/28. The initial situation is:</P>
2077 <PRE> subnet gateway Internet
2078 a.b.c.0/24 a.b.c.1 p.q.r.s</PRE>
2079 where anything from the Internet destined for any machine in
2080 a.b.c.0/24 is routed via p.q.r.s and that gateway knows what to do
2082 <P> Of course it is quite normal for various smaller subnets to exist
2083 behind your friend's gateway. For example, your friend's company might
2084 have a.b.c.16/28=development, a.b.c.32/28=marketing and so on. The
2085 Internet neither knows not cares about this; it just delivers packets
2086 to the p.q.r.s and lets the gateway do whatever needs to be done from
2088 <P> What we want to do is take a subnet, perhaps a.b.c.240/28, out of
2089 your friend's physical location <EM>while still having your friend's
2090 gateway route to it</EM>. As far as the Internet is concerned, you
2091 remain behind that gateway.</P>
2092 <PRE> subnet gateway Internet your gate extruded
2094 a.b.c.0/24 a.b.c.1 p.q.r.s d.e.f.g a.b.c.240/28
2096 ========== tunnel ==========</PRE>
2097 <P>The extruded addresses have to be a complete subnet.</P>
2098 <P>In our example, the friend's security gateway is also his Internet
2099 gateway, but this is not necessary. As long as all traffic from the
2100 Internet to his addresses passes through the Internet gate, the
2101 security gate could be a machine behind that. The IG would need to
2102 route all traffic for the extruded subnet to the SG, and the SG could
2103 handle the rest.</P>
2104 <P>First, configure your subnet using the extruded addresses. Your
2105 security gateway's interface to your subnet needs to have an extruded
2106 address (possibly using a Linux <A href="glossary.html#virtual">
2107 virtual interface</A>, if it also has to have a different address).
2108 Your gateway needs to have a route to the extruded subnet, pointing to
2109 that interface. The other machines at your site need to have
2110 addresses in that subnet, and default routes pointing to your gateway.</P>
2111 <P>If any of your friend's machines need to talk to the extruded
2112 subnet, <EM> they</EM> need to have a route for the extruded subnet,
2113 pointing at his gateway.</P>
2114 <P>Then set up an IPSEC subnet-to-subnet tunnel between your gateway
2115 and his, with your subnet specified as the extruded subnet, and his
2116 subnet specified as "0.0.0.0/0". Do it with manual keying first for
2117 testing, and then with automatic keying for production use.</P>
2118 <P>The tunnel description should be:</P>
2122 leftsubnet=0.0.0.0/0
2124 rightsubnet=a.b.c.0/28
2126 <P> If either side was doing firewalling for the extruded subnet before
2127 the IPSEC connection is set up, ipsec_manual and ipsec_auto need to
2128 know about that (via the {left|right}firewall parameters) so that it
2129 can be overridden for the duration of the connection.</P>
2130 <P> And it all just works. Your SG routes traffic for 0.0.0.0/0 --
2131 that is, the whole Internet -- through the tunnel to his SG, which
2132 then sends it onward as if it came from his subnet. When traffic for
2133 the extruded subnet arrives at his SG, it gets sent through the tunnel
2134 to your SG, which passes it to the right machine.</P>
2135 <P> Remember that when ipsec_manual or ipsec_auto takes a connection
2136 down, it <EM> does not undo the route</EM> it made for that connection.
2137 This lets you take a connection down and bring up a new one, or a
2138 modified version of the old one, without having to rebuild the route
2139 it uses and without any risk of packets which should use IPSEC
2140 accidentally going out in the clear. Because the route always points
2141 into KLIPS, the packets will always go there. Because KLIPS
2142 temporarily has no idea what to do with them (no eroute for them),
2143 they will be discarded.</P>
2144 <P>If you <EM>do</EM> want to take the route down, this is what the
2145 "unroute" operation in manual and auto is for. Just do an unroute
2146 after doing the down.</P>
2147 <P>Note that the route for a connection may have replaced an existing
2148 non-IPSEC route. Nothing in Linux FreeS/WAN will put that pre-IPSEC
2149 route back. If you need it back, you have to create it with the route
2151 <H3><A name="roadvirt">Road Warrior with virtual IP address</A></H3>
2152 <P> Here is a mailing list message about another way to configure for
2153 road warrior support:</P>
2155 Subject: Re: linux-ipsec: understanding the vpn
2156 Date: Thu, 28 Oct 1999 10:43:22 -0400
2157 From: Irving Reid <irving@nevex.com>
2159 > local-------linux------internet------mobile
2163 > now when the mobile user connects to the linux box
2164 > it is given a virtual IP address, i have configured it to
2165 > be in the 10.x.x.x range. mobile user and linux box
2166 > have a tunnel between them with these IP addresses.
2168 > Uptil this all is fine.
2170 If it is possible to configure your mobile client software *not* to
2171 use a virtual IP address, that will make your life easier. It is easier
2172 to configure FreeS/WAN to use the actual address the mobile user gets
2175 Unfortunately, some Windows clients don't let you choose.
2177 > what i would like to know is that how does the mobile
2178 > user communicate with other computers on the local
2179 > LAN , of course with the vpn ?
2181 > what IP address should the local LAN
2182 > computers have ? I guess their default gateway
2183 > should be the linux box ? and does the linux box need
2184 > to be a 2 NIC card box or one is fine.
2186 As someone else stated, yes, the Linux box would usually be the default
2187 IP gateway for the local lan.
2191 If you mobile user has software that *must* use a virtual IP address,
2192 the whole picture changes. Nobody has put much effort into getting
2193 FreeS/WAN to play well in this environment, but here's a sketch of one
2196 Local Lan 1.0.0.0/24
2198 +- Linux FreeS/WAN 1.0.0.2
2208 Virtual Address: 1.0.0.3
2210 Note that the Local Lan network (1.0.0.x) can be registered, routable
2213 Now, the Mobile User sets up an IPSec security association with the
2214 Linux box (1.0.0.2); it should ESP encapsulate all traffic to the
2215 network 1.0.0.x **EXCEPT** UDP port 500. 500/udp is required for the key
2216 negotiation, which needs to work outside of the IPSec tunnel.
2218 On the Linux side, there's a bunch of stuff you need to do by hand (for
2219 now). FreeS/WAN should correctly handle setting up the IPSec SA and
2220 routes, but I haven't tested it so this may not work...
2222 The FreeS/WAN conn should look like:
2226 rightsubnet=1.0.0.0/24
2227 rightnexthop=1.0.0.1
2228 left=0.0.0.0 # The infamous "road warrior"
2229 leftsubnet=1.0.0.3/32
2231 Note that the left subnet contains *only* the remote host's virtual
2234 Hopefully the routing table on the FreeS/WAN box ends up looking like
2238 Kernel IP routing table
2239 Destination Gateway Genmask Flags MSS Window irtt Iface
2240 1.0.0.0 0.0.0.0 255.255.255.0 U 1500 0 0 eth0
2241 127.0.0.0 0.0.0.0 255.0.0.0 U 3584 0 0 lo
2242 0.0.0.0 1.0.0.1 0.0.0.0 UG 1500 0 0 eth0
2243 1.0.0.3 1.0.0.1 255.255.255.255 UG 1433 0 0 ipsec0
2245 So, if anybody sends a packet for 1.0.0.3 to the Linux box, it should
2246 get bundled up and sent through the tunnel. To get the packets for
2247 1.0.0.3 to the Linux box in the first place, you need to use "proxy
2250 How this works is: when a host or router on the local Ethernet segment
2251 wants to send a packet to 1.0.0.3, it sends out an Ethernet level
2252 broadcast "ARP request". If 1.0.0.3 was on the local LAN, it would
2253 reply, saying "send IP packets for 1.0.0.3 to my Ethernet address".
2255 Instead, you need to set up the Linux box so that _it_ answers ARP
2256 requests for 1.0.0.3, even though that isn't its IP address. That
2257 convinces everyone else on the lan to send 1.0.0.3 packets to the Linux
2258 box, where the usual FreeS/WAN processing and routing take over.
2260 % arp -i eth0 -s 1.0.0.3 -D eth0 pub
2262 This says, if you see an ARP request on interface eth0 asking for
2263 1.0.0.3, respond with the Ethernet address of interface eth0.
2265 Now, as I said at the very beginning, if it is *at all* possible to
2266 configure your client *not* to use the virtual IP address, you can avoid
2267 this whole mess.</PRE>
2268 <H3><A name="dynamic">Dynamic Network Interfaces</A></H3>
2269 <P>Sometimes you have to cope with a situation where the network
2270 interface(s) aren't all there at boot. The common example is notebooks
2272 <H4><A name="basicdyn">Basics</A></H4>
2273 <P>The key issue here is that the <VAR>config setup</VAR> section of
2274 the <VAR> /etc/ipsec.conf</VAR> configuration file lists the connection
2275 between ipsecN and hardware interfaces, in the <VAR>interfaces=</VAR>
2276 variable. At any time when <VAR>ipsec setup start</VAR> or <VAR>ipsec
2277 setup restart</VAR> is run this variable <STRONG>must</STRONG>
2278 correspond to the current real situation. More precisely, it <STRONG>
2279 must not</STRONG> mention any hardware interfaces which don't
2280 currently exist. The difficulty is that an <VAR>ipsec setup start</VAR>
2281 command is normally run at boot time so interfaces that are not up
2282 then are mis-handled.</P>
2283 <H4><A name="bootdyn">Boot Time</A></H4>
2284 <P> Normally, an <VAR>ipsec setup start</VAR> is run at boot time.
2285 However, if the hardware situation at boot time is uncertain, one of
2286 two things must be done.</P>
2288 <LI>One possibility is simply not to have IPSEC brought up at boot
2289 time. To do this: </LI>
2290 <PRE> chkconfig --level 2345 ipsec off</PRE>
2291 That's for modern Red Hats or other Linuxes with chkconfig. Systems
2292 which lack this will require fiddling with symlinks in /etc/rc.d/rc?.d
2294 <LI>Another possibility is to bring IPSEC up with no interfaces, which
2295 is less aesthetically satisfying but simpler. Just put </LI>
2299 in the configuration file. KLIPS and Pluto will be started, but won't
2301 <H4><A name="changedyn">Change Time</A></H4>
2302 <P>When the hardware *is* in place, IPSEC has to be made aware of it.
2303 Someday there may be a nice way to do this.</P>
2304 <P>Right now, the way to do it is to fix the <VAR>/etc/ipsec.conf</VAR>
2305 file appropriately, so <VAR>interfaces</VAR> reflects the new
2306 situation, and then restart the IPSEC subsystem. This does break any
2307 existing IPSEC connections.</P>
2308 <P>If IPSEC wasn't brought up at boot time, do</P>
2309 <PRE> ipsec setup start</PRE>
2311 <PRE> ipsec setup restart</PRE>
2312 which won't be as quick.
2313 <P>If some of the hardware is to be taken out, before doing that, amend
2314 the configuration file so interfaces no longer includes it, and do</P>
2315 <PRE> ipsec setup restart</PRE>
2316 <P>Again, this breaks any existing connections.</P>
2317 <H3><A name="unencrypted">Unencrypted tunnels</A></H3>
2318 <P> Sometimes you might want to create a tunnel without encryption.
2319 Often this is a bad idea, even if you have some data which need not be
2320 private. See this <A href="ipsec.html#traffic.resist">discussion</A>. </P>
2321 <P> The IPSEC protocols provide two ways to do build such tunnels: </P>
2323 <DT>using ESP with null encryption </DT>
2324 <DD>not supported by FreeS/WAN </DD>
2325 <DT>using <A href="glossary.html#AH">AH</A> without <A href="glossary.html#ESP">
2327 <DD>supported for manually keyed connections </DD>
2328 <DD>possible with explicit commands via <A href="manpage.d/ipsec_whack.8.html">
2329 ipsec_whack(8)</A> (see this <A href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00190.html">
2330 list message</A>) </DD>
2331 <DD>not supported in the <A href="manpage.d/ipsec_auto.8.html">
2332 ipsec_auto(8)</A> scripts. </DD>
2334 One situation in which this comes up is when otherwise some data would
2335 be encrypted twice. Alice wants a secure tunnel from her machine to
2336 Bob's. Since she's behind one security gateway and he's behind another,
2337 part of the tunnel that they build passes through the tunnel that their
2338 site admins have built between the gateways. All of Alice and Bob's
2339 messages are encrypted twice.
2340 <P> There are several ways to handle this.</P>
2342 <LI>Just accept the overhead of double encryption. The site admins
2343 might choose this if any of the following apply:
2345 <LI>policy says encrypt everything (usually, it should) </LI>
2346 <LI>they don't entirely trust Alice and Bob (usually, if they don't
2347 have to, they shouldn't) </LI>
2348 <LI>if they don't feel the saved cycles are worth the time they'd need
2349 to build a non-encrypted tunnel for Alice and Bob's packets (often,
2353 <LI>Use a plain IP-in-IP tunnel. These are not well documented. A good
2354 starting point is in the Linux kernel source tree, in
2355 /usr/src/linux/drivers/net/README.tunnel.</LI>
2356 <LI>Use a manually-keyed AH-only tunnel.</LI>
2358 <P> Note that if Alice and Bob want end-to-end security, they must
2359 build a tunnel end-to-end between their machines or use some other
2360 end-to-end tool such as PGP or SSL that suits their data. The only
2361 question is whether the admins build some special unencrypted tunnel
2362 for those already-encrypted packets. </P>
2364 <A HREF="toc.html">Contents</a>
2365 <A HREF="install.html">Previous</a>
2366 <A HREF="manpages.html">Next</a>
OSDN Git Service
