diff options
| author | Rene Mayrhofer <rene@mayrhofer.eu.org> | 2006-05-22 05:12:18 +0000 |
|---|---|---|
| committer | Rene Mayrhofer <rene@mayrhofer.eu.org> | 2006-05-22 05:12:18 +0000 |
| commit | aa0f5b38aec14428b4b80e06f90ff781f8bca5f1 (patch) | |
| tree | 95f3d0c8cb0d59d88900dbbd72110d7ab6e15b2a /doc/src | |
| parent | 7c383bc22113b23718be89fe18eeb251942d7356 (diff) | |
| download | vyos-strongswan-aa0f5b38aec14428b4b80e06f90ff781f8bca5f1.tar.gz vyos-strongswan-aa0f5b38aec14428b4b80e06f90ff781f8bca5f1.zip | |
Import initial strongswan 2.7.0 version into SVN.
Diffstat (limited to 'doc/src')
52 files changed, 29575 insertions, 0 deletions
diff --git a/doc/src/.cvsignore b/doc/src/.cvsignore new file mode 100644 index 000000000..3ed29bc59 --- /dev/null +++ b/doc/src/.cvsignore @@ -0,0 +1,3 @@ +foo.xml +foobar.html +makecheck-2.html diff --git a/doc/src/adv_config.html b/doc/src/adv_config.html new file mode 100644 index 000000000..ab6901b5e --- /dev/null +++ b/doc/src/adv_config.html @@ -0,0 +1,1412 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>Advanced FreeS/WAN configuration</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, configuration"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Maintained by Claudia Schmeing for same. + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: adv_config.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="adv_config">Other configuration possibilities</a></h1> + +<p>This document describes various options for FreeS/WAN configuration which +are less used or more complex (often both) than the standard cases described +in our <a href="config.html#config">config</a> and +<a href="quickstart.html#quick_guide">quickstart</a> documents.</p> + +<h2><a name="thumb">Some rules of thumb about configuration</a></h2> + +<h3><a name="cheap.tunnel">Tunnels are cheap</a></h3> + +<p>Nearly all of the overhead in IPsec processing is in the encryption and +authentication of packets. Our <a href="performance.html">performance</a> +document discusses these overheads.</p> + +<p>Beside those overheads, the cost of managing additional tunnels is +trivial. Whether your gateway supports one tunnel or ten just does not +matter. A hundred might be a problem; there is a <a +href="performance.html#biggate">section</a> on this in the performance +document.</p> + +<p>So, in nearly all cases, if using multiple tunnels gives you a reasonable +way to describe what you need to do, you should describe it that way in your +configuration files.</p> + +<p>For example, one user recently asked on a mailing list about this network +configuration:</p> +<pre> netA---gwA---gwB---netB + |----netC + + netA and B are secured netC not. + netA and gwA can not access netC</pre> + +<p>The user had constructed only one tunnel, netA to netB, and wanted to know +how to use ip-route to get netC packets into it. This is entirely +unnecessary. One of the replies was:</p> +<pre> The simplest way and indeed the right way to + solve this problem is to set up two connections: + + leftsubnet=NetA + left=gwA + right=gwB + rightsubnet=NetB + and + leftsubnet=NetA + left=gwA + right=gwB + rightsubnet=NetC</pre> + +<p>This would still be correct even if we added nets D, E, F, +... to the above diagram and needed twenty tunnels.</p> + +<p>Of course another possibility would be to just use one tunnel, with a +subnet mask that includes both netB and netC (or B, C, D, ...). See next +section.</p> + +<p>In general, you can construct as many tunnels as you need. Networks like +netC in this example that do not connect directly to the gateway are fine, as +long as the gateway can route to them.</p> + +<p>The number of tunnels can become an issue if it reaches 50 or so. This is +discussed in the <a href="performance.html#biggate">performance</a> document. +Look there for information on supporting hundreds of Road Warriors from one +gateway.</p> + +<p>If you find yourself with too many tunnels for some reason like having +eight subnets at one location and nine at another so you end up with +9*8=72 tunnels, read the next section here.</p> + +<h3><a name="subnet.size">Subnet sizes</a></h3> + +<p>The subnets used in <var>leftsubnet</var> and <var>rightsubnet</var> can +be of any size that fits your needs, and they need not correspond to physical +networks.</p> + +<p>You adjust the size by changing the <a href="glossary.html#subnet">subnet +mask</a>, the number after the slash in the subnet description. For +example</p> +<ul> + <li>in 192.168.100.0/24 the /24 mask says 24 bits are used to designate the + network. This leave 8 bits to label machines. This subnet has 256 + addresses. .0 and .255 are reserved, so it can have 254 machines.</li> + <li>A subnet with a /23 mask would be twice as large, 512 addresses.</li> + <li>A subnet with a /25 mask would be half the size, 128 addresses.</li> + <li>/0 is the whole Internet</li> + <li>/32 is a single machine</li> +</ul> + +<p>As an example of using these in connection descriptions, suppose your +company's head office has four physical networks using the address ranges:</p> +<dl> + <dt>192.168.100.0/24</dt> + <dd>development</dd> + <dt>192.168.101.0/24</dt> + <dd>production</dd> + <dt>192.168.102.0/24</dt> + <dd>marketing</dd> + <dt>192.168.103.0/24</dt> + <dd>administration</dd> +</dl> + +<p>You can use exactly those subnets in your connection descriptions, or use +larger subnets to grant broad access if required:</p> +<dl> + <dt>leftsubnet=192.168.100.0/24</dt> + <dd>remote hosts can access only development</dd> + <dt>leftsubnet=192.168.100.0/23</dt> + <dd>remote hosts can access development or production</dd> + <dt>leftsubnet=192.168.102.0/23</dt> + <dd>remote hosts can access marketing or administration</dd> + <dt>leftsubnet=192.168.100.0/22</dt> + <dd>remote hosts can access any of the four departments</dd> +</dl> + +<p>or use smaller subnets to restrict access:</p> +<dl> + <dt>leftsubnet=192.168.103.0/24</dt> + <dd>remote hosts can access any machine in administration</dd> + <dt>leftsubnet=192.168.103.64/28</dt> + <dd>remote hosts can access only certain machines in administration.</dd> + <dt>leftsubnet=192.168.103.42/32</dt> + <dd>remote hosts can access only one particular machine in + administration</dd> +</dl> + +<p>To be exact, 192.68.103.64/28 means all addresses whose top 28 bits match +192.168.103.64. There are 16 of these because there are 16 possibilities for +the remainingg 4 bits. Their addresses are 192.168.103.64 to +192.168.103.79.</p> + +<p>Each connection description can use a different subnet if required.</p> + +<p>It is possible to use all the examples above on the same FreeS/WAN +gateway, each in a different connection description, perhaps for different +classes of user or for different remote offices.</p> + +<p>It is also possible to have multiple tunnels using different +<var>leftsubnet</var> descriptions with the same <var>right</var>. For +example, when the marketing manager is on the road he or she might have +access to:</p> +<dl> + <dt>leftsubnet=192.168.102.0/24</dt> + <dd>all machines in marketing</dd> + <dt>192.168.101.32/29</dt> + <dd>some machines in production</dd> + <dt>leftsubnet=192.168.103.42/32</dt> + <dd>one particular machine in administration</dd> +</dl> + +<p>This takes three tunnels, but tunnels are cheap. If the laptop is set up +to build all three tunnels automatically, then he or she can access all these +machines concurrently, perhaps from different windows.</p> + +<h3><a name="example.more">Other network layouts</a></h3> + +<p>Here is the usual network picture for a site-to-site VPN::</p> +<pre> Sunset==========West------------------East=========Sunrise + local net untrusted net local net</pre> + +<p>and for the Road Warrior::</p> +<pre> telecommuter's PC or + traveller's laptop + Sunset==========West------------------East + corporate LAN untrusted net</pre> + +<p>Other configurations are also possible.</p> + +<h4><a name="internet.subnet">The Internet as a big subnet</a></h4> + +<p>A telecommuter might have:</p> +<pre> Sunset==========West------------------East ================= firewall --- the Internet + home network untrusted net corporate network</pre> + +<p>This can be described as a special case of the general subnet-to-subnet +connection. The subnet on the right is 0.0.0.0/0, the whole Internet.</p> + +<p>West (the home gateway) can have its firewall rules set up so that only +IPsec packets to East are allowed out. It will then behave as if its only +connection to the world was a wire to East.</p> + +<p>When machines on the home network need to reach the Internet, they do so +via the tunnel, East and the corporate firewall. From the viewpoint of the +Internet (perhaps of some EvilDoer trying to break in!), those home office +machines are behind the firewall and protected by it.</p> + +<h4><a name="wireless.config">Wireless</a></h4> + +<p>Another possible configuration comes up when you do not trust the local +network, either because you have very high security standards or because your +are using easily-intercepted wireless signals.</p> + +<p>Some wireless networks have built-in encryption called <a +href="glossary.html#WEP">WEP</a>, but its security is dubious. It is a fairly +common practice to use IPsec instead.</p> + +<p>In this case, part of your network may look like this:</p> +<pre> West-----------------------------East == the rest of your network + workstation untrusted wireless net</pre> + +<p>Of course, there would likely be several wireless workstations, each with +its own IPsec tunnel to the East gateway.</p> + +<p>The connection descriptions look much like Road Warrior descriptions:</p> +<ul> + <li>each workstation should have its own unique + <ul> + <li>identifier for IPsec</li> + <li>RSA key</li> + <li>connection description.</li> + </ul> + </li> + <li>on the gateway, use <var>left=%any</var>, or the workstation IP + address</li> + <li>on workstations, <var>left=%defaultroute</var>, or the workstation IP + address</li> + <li><var>leftsubnet=</var> is not used.</li> +</ul> + +<p>The <var>rightsubnet=</var> parameter might be set in any of several +ways:</p> +<dl> + <dt>rightsubnet=0.0.0.0/0</dt> + <dd>allowing workstations to access the entire Internet (see <a + href="#internet.subnet">above</a>)</dd> + <dt>rightsubnet=a.b.c.0/24</dt> + <dd>allowing access to your entire local network</dd> + <dt>rightsubnet=a.b.c.d/32</dt> + <dd>restricting the workstation to connecting to a particular server</dd> +</dl> + +<p>Of course you can mix and match these as required. For example, a +university might allow faculty full Internet access while letting student +laptops connect only to a group of lab machines.</p> + +<h2><a name="choose">Choosing connection types</a></h2> + +<p>One choice you need to make before configuring additional connections is +what type or types of connections you will use. There are several options, +and you can use more than one concurrently.</p> + +<h3><a name="man-auto">Manual vs. automatic keying</a></h3> + +<p>IPsec allows two types of connections, with manual or automatic keying. +FreeS/WAN starts them with commands such as:</p> +<pre> ipsec manual --up <var>name</var> + ipsec auto --up <var>name</var></pre> + +<p>The difference is in how they are keyed.</p> +<dl> + <dt><a href="glossary.html#manual">Manually keyed</a> connections</dt> + <dd>use keys stored in <a + href="manpage.d/ipsec.conf.5.html">ipsec.conf</a>.</dd> + <dt><a href="glossary.html#auto">Automatically keyed</a> connections</dt> + <dd>use keys automatically generated by the Pluto key negotiation daemon. + The key negotiation protocol, <a href="glossary.html#IKE">IKE</a>, must + authenticate the other system. (It is vulnerable to a <a + href="glossary.html#middle">man-in-the-middle attack</a> if used + without authentication.) We currently support two authentication + methods: + <ul> + <li>using shared secrets stored in <a + href="manpage.d/ipsec.secrets.5.html">ipsec.secrets</a>.</li> + <li>RSA <a href="glossary.html#public">public key</a> authentication, + with our machine's private key in <a + href="manpage.d/ipsec.secrets.5.html">ipsec.secrets</a>. Public + keys for other machines may either be placed in <a + href="manpage.d/ipsec.conf.5.html">ipsec.conf</a> or provided via + DNS.</li> + </ul> + <p>A third method, using RSA keys embedded in <a + href="glossary.html#X509">X.509</a> certtificates, is provided by + user <a href="web.html#patch">patches</a>.</p> + </dd> +</dl> + +<p><a href="glossary.html#manual">Manually keyed</a> connections provide +weaker security than <a href="glossary.html#auto">automatically keyed</a> +connections. An opponent who reads ipsec.secrets(5) gets your encryption key +and can read all data encrypted by it. If he or she has an archive of old +messages, all of them back to your last key change are also readable.</p> + +<p>With automatically-(re)-keyed connections, an opponent who reads +ipsec.secrets(5) gets the key used to authenticate your system in IKE -- the +shared secret or your private key, depending what authentication mechanism is +in use. However, he or she does not automatically gain access to any +encryption keys or any data.</p> + +<p>An attacker who has your authentication key can mount a <a +href="glossary.html#middle">man-in-the-middle attack</a> and, if that +succeeds, he or she will get encryption keys and data. This is a serious +danger, but it is better than having the attacker read everyting as soon as +he or she breaks into ipsec.secrets(5).. Moreover, the keys change often so +an opponent who gets one key does not get a large amount of data. To read all +your data, he or she would have to do a man-in-the-middle attack at every key +change.</p> + +<p>We discuss using <a href="#prodman">manual keying in production</a> below, +but this is <strong>not recommended</strong> except in special circumstances, +such as needing to communicate with some implementation that offers no +auto-keyed mode compatible with FreeS/WAN.</p> + +<p>Manual keying may also be useful for testing. There is some discussion of +this in our <a href="faq.html#man4debug">FAQ</a>.</p> + +<h3><a name="auto-auth">Authentication methods for auto-keying</a></h3> + +<p>The IKE protocol which Pluto uses to negotiate connections between +gateways must use some form of authentication of peers. A gateway must know +who it is talking to before it can create a secure connection. We support two +basic methods for this authentication:</p> +<ul> + <li>shared secrets, stored in <a + href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a></li> + <li>RSA authentication</li> +</ul> + +<p>There are, howver, several variations on the RSA theme, using different +methods of managing the RSA keys:</p> +<ul> + <li>our RSA private key in <a + href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> with other + gateways' public keys + <dl> + <dt>either</dt> + <dd>stored in <a + href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a></dd> + <dt>or</dt> + <dd>looked up via <a href="glossary.html#DNS">DNS</a></dd> + </dl> + </li> + <li>authentication with <a href="glossary.html#x509">x.509</a> + certificates.; See our <a href="web.html#patch">links section</a> for + information on user-contributed patches for this.:</li> +</ul> + +<p>Public keys in <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5</a>) +give a reasonably straightforward method of specifying keys for explicitly +configured connections.</p> + +<p>Putting public keys in DNS allows us to support <a +href="glossary.html#carpediem">opportunistic encryption</a>. Any two +FreeS/WAN gateways can provide secure communication, without either of them +having any preset information about the other.</p> + +<p>X.509 certificates may be required to interface to various <a +href="glossary.html#PKI">PKI</a>s.</p> + +<h3><a name="adv-pk">Advantages of public key methods</a></h3> + +<p>Authentication with a <a href="glossary.html#public">public key</a> method +such as <a href="glossary.html#RSA">RSA</a> has some important advantages +over using shared secrets.</p> +<ul> + <li>no problem of secure transmission of secrets + <ul> + <li>A shared secret must be shared, so you have the problem of + transmitting it securely to the other party. If you get this wrong, + you have no security.</li> + <li>With a public key technique, you transmit only your public key. The + system is designed to ensure that it does not matter if an enemy + obtains public keys. The private key never leaves your machine.</li> + </ul> + </li> + <li>easier management + <ul> + <li>Suppose you have 20 branch offices all connecting to one gateway at + head office, and all using shared secrets. Then the head office admin + has 20 secrets to manage. Each of them must be kept secret not only + from outsiders, but also from 19 of the branch office admins. The + branch office admins have only one secret each to manage. + <p>If the branch offices need to talk to each other, this becomes + problematic. You need another 20*19/2 = 190 secrets for + branch-to-branch communication, each known to exactly two branches. + Now all the branch admins have the headache of handling 20 keys, each + shared with exactly one other branch or with head office.</p> + <p>For larger numbers of branches, the number of connections and + secrets increases quadratically and managing them becomes a + nightmare. A 1000-gateway fully connected network needs 499,500 + secrets, each known to exactly two players. There are ways to reduce + this problem, for example by introducing a central key server, but + these involve additional communication overheads, more administrative + work, and new threats that must be carefully guarded against.</p> + </li> + <li>With public key techniques, the <em>only</em> thing you have to + keep secret is your private key, and <em>you keep that secret from + everyone</em>. + <p>As network size increaes, the number of public keys used increases + linearly with the number of nodes. This still requires careful + administration in large applications, but is nothing like the + disaster of a quadratic increase. On a 1000-gateway network, you have + 1000 private keys, each of which must be kept secure on one machine, + and 1000 public keys which must be distributed. This is not a trivial + problem, but it is manageable.</p> + </li> + </ul> + </li> + <li>does not require fixed IP addresses + <ul> + <li>When shared secrets are used in IPsec, the responder must be able + to tell which secret to use by looking at the IP address on the + incoming packets. When the other parties do not have a fixed IP + address to be identified by (for example, on nearly all dialup ISP + connections and many cable or ADSL links), this does not work well -- + all must share the same secret!</li> + <li>When RSA authentication is in use, the initiator can identify + itself by name before the key must be determined. The responder then + checks that the message is signed with the public key corresponding + to that name.</li> + </ul> + </li> +</ul> + +<p>There is also a disadvantage:</p> +<ul> + <li>your private key is a single point of attack, extremely valuable to an + enemy + <ul> + <li>with shared secrets, an attacker who steals your ipsec.secrets file + can impersonate you or try <a + href="glossary.html#middle">man-in-the-middle</a> attacks, but can + only attack connections described in that file</li> + <li>an attacker who steals your private key gains the chance to attack + not only existing connections <em>but also any future + connections</em> created using that key</li> + </ul> + </li> +</ul> + +<p>This is partly counterbalanced by the fact that the key is never +transmitted and remains under your control at all times. It is likely +necessary, however, to take account of this in setting security policy. For +example, you should change gateway keys when an administrator leaves the +company, and should change them periodically in any case.</p> + +<p>Overall, public key methods are <strong>more secure, more easily managed +and more flexible</strong>. We recommend that they be used for all +connections, unless there is a compelling reason to do otherwise.</p> + +<h2><a name="prodsecrets">Using shared secrets in production</a></h2> + +<p>Generally, public key methods are preferred for reasons given above, but +shared secrets can be used with no loss of security, just more work and +perhaps more need to take precautions.</p> + +<p>What I call "shared secrets" are sometimes also called "pre-shared keys". +They are used only for for authentication, never for encryption. Calling them +"pre-shared keys" has confused some users into thinking they were encryption +keys, so I prefer to avoid the term..</p> + +<p>If you are interoperating with another IPsec implementation, you may find +its documentation calling them "passphrases".</p> + +<h3><a name="secrets">Putting secrets in ipsec.secrets(5)</a></h3> + +<p>If shared secrets are to be used to <a +href="glossary.html#authentication">authenticate</a> communication for the <a +href="glossary.html#DH">Diffie-Hellman</a> key exchange in the <a +href="glossary.html#IKE">IKE</a> protocol, then those secrets must be stored +in <var>/etc/ipsec.secrets</var>. For details, see the <a +href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> man page.</p> + +<p>A few considerations are vital:</p> +<ul> + <li>make the secrets long and unguessable. Since they need not be + remembered by humans, very long ugly strings may be used. We suggest + using our <a href="manpage.d/ipsec_ranbits.8.html">ipsec_ranbits(8)</a> + utility to generate long (128 bits or more) random strings.</li> + <li>transmit secrets securely. You have to share them with other systems, + but you lose if they are intercepted and used against you. Use <a + href="glossary.html#PGP">PGP</a>, <a href="glossary.html#SSH">SSH</a>, + hand delivery of a floppy disk which is then destroyed, or some other + trustworthy method to deliver them.</li> + <li>store secrets securely, in root-owned files with permissions + rw------.</li> + <li>limit sharing of secrets. Alice, Bob, Carol and Dave may all talk to + each other, but only Alice and Bob should know the secret for an + Alice-Bob link.</li> + <li><strong>do not share private keys</strong>. The private key for RSA + authentication of your system is stored in <a + href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a>, but it is a + different class of secret from the pre-shared keys used for the "shared + secret" authentication. No-one but you should have the RSA private + key.</li> +</ul> + +<p>Each line has the IP addresses of the two gateways plus the secret. It +should look something like this:</p> +<pre> 10.0.0.1 11.0.0.1 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"</pre> + +<p><var>PSK</var> indicates the use of a +<strong>p</strong>re-<strong>s</strong>hared <strong>k</strong>ey. The quotes +and the whitespace shown are required.</p> + +<p>You can use any character string as your secret. For security, it should +be both long and extremely hard to guess. We provide a utility to generate +such strings, <a +href="manpage.d/ipsec_ranbits.8.html">ipsec_ranbits(8)</a>.</p> + +<p>You want the same secret on the two gateways used, so you create a line +with that secret and the two gateway IP addresses. The installation process +supplies an example secret, useful <em>only</em> for testing. You must change +it for production use.</p> + +<h3><a name="securing.secrets">File security</a></h3> + +<p>You must deliver this file, or the relevant part of it, to the other +gateway machine by some <strong>secure</strong> means. <em>Don't just FTP or +mail the file!</em> It is vital that the secrets in it remain secret. An +attacker who knew those could easily have <em>all the data on your "secure" +connection</em>.</p> + +<p>This file must be owned by root and should have permissions +<var>rw-------</var>.</p> + +<h3><a name="notroadshared">Shared secrets for road warriors</a></h3> + +<p>You can use a shared secret to support a single road warrior connecting to +your gateway, and this is a reasonable thing to do in some circumstances. +Public key methods have advantages, discussed <a href="#choose">above</a>, +but they are not critical in this case.</p> + +<p>To do this, the line in ipsec.secrets(5) is something like:</p> +<pre> 10.0.0.1 0.0.0.0 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"</pre> +where the <var>0.0.0.0</var> means that any IP address is acceptable. + +<p><strong>For more than one road warrior, shared secrets are <em>not</em> +recommended.</strong> If shared secrets are used, then when the responder +needs to look up the secret, all it knows about the sender is an IP address. +This is fine if the sender is at a fixed IP address specified in the config +file. It is also fine if only one road warrior uses the wildcard +<var>0.0.0.0</var> address. However, if you have more than one road warrior +using shared secret authentication, then they must all use that wildcard and +therefore <strong>all road warriors using PSK autentication must use the same +secret</strong>. Obviously, this is insecure.</p> + +<p><strong>For multiple road warriors, use public key +authentication.</strong> Each roadwarrior can then have its own identity (our +<var>leftid=</var> or <var>rightid=</var> parameters), its own public/private +key pair, and its own secure connection.</p> + +<h2><a name="prodman">Using manual keying in production</a></h2> + +<p>Generally, <a href="glossary.html#auto">automatic keying</a> is preferred +over <a href="glossary.html#manual">manual keying</a> for production use +because it is both easier to manage and more secure. Automatic keying frees +the admin from much of the burden of managing keys securely, and can provide +<a href="glossary.html#PFS">perfect forward secrecy</a>. This is discussed in +more detail <a href="#man-auto">above</a>.</p> + +<p>However, it is possible to use manual keying in production if that is what +you want to do. This might be necessary, for example, in order to +interoperate with some device that either does not provide automatic keying +or provides it in some version we cannot talk to.</p> + +<p>Note that with manual keying <strong>all security rests with the +keys</strong>. If an adversary acquires your keys, you've had it. He or she +can read everything ever sent with those keys, including old messages he or +she may have archived.</p> + +<p>You need to <strong>be really paranoid about keys</strong> if you're going +to rely on manual keying for anything important.</p> +<ul> + <li>keep keys in files with 600 permissions, owned by root</li> + <li>be extremely careful about security of your gateway systems. Anyone who + breaks into a gateway and gains root privileges can get all your keys and + read everything ever encrypted with those keys, both old messages he has + archived and any new ones you may send.</li> + <li>change keys regularly. This can be a considerable bother, (and provides + an excellent reason to consider automatic keying instead), but it is + <em>absolutely essential</em> for security. Consider a manually keyed + system in which you leave the same key in place for months: + <ul> + <li>an attacker can have a very large sample of text sent with that key + to work with. This makes various cryptographic attacks much more + likely to succeed.</li> + <li>The chances of the key being compromised in some non-cryptographic + manner -- a spy finds it on a discarded notepad, someone breaks into + your server or your building and steals it, a staff member is bribed, + tricked, seduced or coerced into revealing it, etc. -- also increase + over time.</li> + <li>a successful attacker can read everything ever sent with that key. + This makes any successful attack extremely damaging.</li> + </ul> + It is clear that you must change keys often to have any useful security. + The only question is how often.</li> + <li>use <a href="glossary.html#PGP">PGP</a> or <a + href="glossary.html#SSH">SSH</a> for all key transfers</li> + <li>don't edit files with keys in them when someone can look over your + shoulder</li> + <li>worry about network security; could someone get keys by snooping + packets on the LAN between your X desktop and the gateway?</li> + <li>lock up your backup tapes for the gateway system</li> + <li>... and so on</li> +</ul> + +<p>Linux FreeS/WAN provides some facilities to help with this. In particular, +it is good policy to <strong>keep keys in separate files</strong> so you can +edit configuration information in /etc/ipsec.conf without exposing keys to +"shoulder surfers" or network snoops. We support this with the +<var>also=</var> and <var>include</var> syntax in <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.</p> + +<p>See the last example in our <a href="examples">examples</a> file. In the +/etc/ipsec.conf <var>conn samplesep</var> section, it has the line:</p> +<pre> also=samplesep-keys</pre> + +<p>which tells the "ipsec manual" script to insert the configuration +description labelled "samplesep-keys" if it can find it. The /etc/ipsec.conf +file must also have a line such as:</p> +<pre>include ipsec.*.conf</pre> + +<p>which tells it to read other files. One of those other files then might +contain the additional data:</p> +<pre>conn samplesep-keys + spi=0x200 + esp=3des-md5-96 + espenckey=0x01234567_89abcdef_02468ace_13579bdf_12345678_9abcdef0 + espauthkey=0x12345678_9abcdef0_2468ace0_13579bdf</pre> + +<p>The first line matches the label in the "also=" line, so the indented +lines are inserted. The net effect is exactly as if the inserted lines had +occurred in the original file in place of the "also=" line.</p> + +<p>Variables set here are:</p> +<dl> + <dt>spi</dt> + <dd>A number needed by the manual keying code. Any 3-digit hex number + will do, but if you have more than one manual connection then + <strong>spi must be different</strong> for each connection.</dd> + <dt>esp</dt> + <dd>Options for <a href="glossary.html#ESP">ESP</a> (Encapsulated + Security Payload), the usual IPsec encryption mode. Settings here are + for <a href="glossary.html#encryption">encryption</a> using <a + href="glossary.html#3DES">triple DES</a> and <a + href="glossary.html#authentication">authentication</a> using <a + href="glossary.html#MD5">MD5</a>. Note that encryption without + authentication should not be used; it is insecure.</dd> + <dt>espenkey</dt> + <dd>Key for ESP encryption. Here, a 192-bit hex number for triple + DES.</dd> + <dt>espauthkey</dt> + <dd>Key for ESP authentication. Here, a 128-bit hex number for MD5.</dd> +</dl> + +<p><strong>Note</strong> that the <strong>example keys we supply</strong> are +intended <strong>only for testing</strong>. For real use, you should go to +automatic keying. If that is not possible, create your own keys for manual +mode and keep them secret</p> + +<p>Of course, any files containing keys <strong>must</strong> have 600 +permissions and be owned by root.</p> + +<p>If you connect in this way to multiple sites, we recommend that you keep +keys for each site in a separate file and adopt some naming convention that +lets you pick them all up with a single "include" line. This minimizes the +risk of losing several keys to one error or attack and of accidentally giving +another site admin keys which he or she has no business knowing.</p> + +<p>Also note that if you have multiple manually keyed connections on a single +machine, then the <var>spi</var> parameter must be different for each one. +Any 3-digit hex number is OK, provided they are different for each +connection. We reserve the range 0x100 to 0xfff for manual connections. Pluto +assigns SPIs from 0x1000 up for automatically keyed connections.</p> + +<p>If <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> contains keys +for manual mode connections, then it too must have permissions +<var>rw-------</var>. We recommend instead that, if you must manual keying in +production, you keep the keys in separate files.</p> + +<p>Note also that <a href="manpage.d/ipsec.conf.5.html">ipsec.conf</a> is +installed with permissions <var>rw-r--r--</var>. If you plan to use manually +keyed connections for anything more than initial testing, you <b>must</b>:</p> +<ul> + <li>either change permissions to <var>rw-------</var></li> + <li>or store keys separately in secure files and access them via include + statements in <a href="manpage.d/ipsec.conf.5.html">ipsec.conf</a>.</li> +</ul> + +<p>We recommend the latter method for all but the simplest configurations.</p> + +<h3><a name="ranbits">Creating keys with ranbits</a></h3> + +<p>You can create new <a href="glossary.html#random">random</a> keys with the +<a href="manpage.d/ipsec_ranbits.8.html">ranbits(8)</a> utility. For example, +the commands:</p> +<pre> umask 177 + ipsec ranbits 192 > temp + ipsec ranbits 128 >> temp</pre> + +<p>create keys in the sizes needed for our default algorithms:</p> +<ul> + <li>192-bit key for <a href="glossary.html#3DES">3DES</a> encryption <br> + (only 168 bits are used; parity bits are ignored)</li> + <li>128-bit key for keyed <a href="glossary.html#MD5">MD5</a> + authentication</li> +</ul> + +<p>If you want to use <a href="glossary.html#SHA">SHA</a> instead of <a +href="glossary.html#MD5">MD5</a>, that requires a 160-bit key</p> + +<p>Note that any <strong>temporary files</strong> used must be kept +<strong>secure</strong> since they contain keys. That is the reason for the +umask command above. The temporary file should be deleted as soon as you are +done with it. You may also want to change the umask back to its default value +after you are finished working on keys.</p> + +<p>The ranbits utility may pause for a few seconds if not enough entropy is +available immediately. See ipsec_ranbits(8) and random(4) for details. You +may wish to provide some activity to feed entropy into the system. For +example, you might move the mouse around, type random characters, or do +<var>du /usr > /dev/null</var> in the background.</p> + +<h2><a name="boot">Setting up connections at boot time</a></h2> + +<p>You can tell the system to set up connections automatically at boot time +by putting suitable stuff in /etc/ipsec.conf on both systems. The relevant +section of the file is labelled by a line reading <var>config setup</var>.</p> + +<p>Details can be found in the <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> man page. We also +provide a file of <a href="examples">example configurations</a>.</p> + +<p>The most likely options are something like:</p> +<dl> + <dt>interfaces="ipsec0=eth0 ipsec1=ppp0"</dt> + <dd>Tells KLIPS which interfaces to use. Up to four interfaces numbered + ipsec[0-3] are supported. Each interface can support an arbitrary + number of tunnels. + <p>Note that for PPP, you give the ppp[0-9] device name here, not the + underlying device such as modem (or eth1 if you are using PPPoE).</p> + </dd> + <dt>interfaces=%defaultroute</dt> + <dd>Alternative setting, useful in simple cases. KLIPS will pick up both + its interface and the next hop information from the settings of the + Linux default route.</dd> + <dt>forwardcontrol=no</dt> + <dd>Normally "no". Set to "yes" if the IP forwarding option is disabled + in your network configuration. (This can be set as a kernel + configuration option or later. e.g. on Redhat, it's in + /etc/sysconfig/network and on SuSE you can adjust it with Yast.) Linux + FreeS/WAN will then enable forwarding when starting up and turn it off + when going down. This is used to ensure that no packets will be + forwarded before IPsec comes up and takes control.</dd> + <dt>syslog=daemon.error</dt> + <dd>Used in messages to the system logging daemon (syslogd) to specify + what type of software is sending the messages. If the settings are + "daemon.error" as in our example, then syslogd treats the messages as + error messages from a daemon. + <p>Note that <a href="glossary.html#Pluto">Pluto</a> does not currently + pay attention to this variable. The variable controls setup messages + only.</p> + </dd> + <dt>klipsdebug=</dt> + <dd>Debug settings for <a href="glossary.html#KLIPS">KLIPS</a>.</dd> + <dt>plutodebug=</dt> + <dd>Debug settings for <a href="glossary.html#Pluto">Pluto</a>.</dd> + <dt>... for both the above DEBUG settings</dt> + <dd>Normally, leave empty as shown above for no debugging output.<br> + Use "all" for maximum information.<br> + See ipsec_klipsdebug(8) and ipsec_pluto(8) man page for other options. + Beware that if you set /etc/ipsec.conf to enable debug output, your + system's log files may get large quickly.</dd> + <dt>dumpdir=/safe/directory</dt> + <dd>Normally, programs started by ipsec setup don't crash. If they do, by + default, no core dump will be produced because such dumps would contain + secrets. If you find you need to debug such crashes, you can set + dumpdir to the name of a directory in which to collect the core + file.</dd> + <dt>manualstart=</dt> + <dd>List of manually keyed connections to be automatically started at + boot time. Useful for testing, but not for long term use. Connections + which are automatically started should also be automatically + re-keyed.</dd> + <dt>pluto=yes</dt> + <dd>Whether to start <a href="glossary.html#Pluto">Pluto</a> when ipsec + startup is done.<br> + This parameter is optional and defaults to "yes" if not present. + <p>"yes" is strongly recommended for production use so that the keying + daemon (Pluto) will automatically re-key the connections regularly. The + ipsec-auto parameters ikelifetime, ipseclifetime and reykeywindow give + you control over frequency of rekeying.</p> + </dd> + <dt>plutoload="reno-van reno-adam reno-nyc"</dt> + <dd>List of tunnels (by name, e.g. fred-susan or reno-van in our + examples) to be loaded into Pluto's internal database at startup. In + this example, Pluto loads three tunnels into its database when it is + started. + <p>If plutoload is "%search", Pluto will load any connections whose + description includes "auto=add" or "auto=start".</p> + </dd> + <dt>plutostart="reno-van reno-adam reno-nyc"</dt> + <dd>List of tunnels to attempt to negotiate when Pluto is started. + <p>If plutostart is "%search", Pluto will start any connections whose + description includes "auto=start".</p> + <p>Note that, for a connection intended to be permanent, <strong>both + gateways should be set try to start</strong> the tunnel. This allows + quick recovery if either gateway is rebooted or has its IPsec + restarted. If only one gateway is set to start the tunnel and the other + gateway restarts, the tunnel may not be rebuilt.</p> + </dd> + <dt>plutowait=no</dt> + <dd>Controls whether Pluto waits for one tunnel to be established before + starting to negotiate the next. You might set this to "yes" + <ul> + <li>if your gateway is a very limited machine and you need to + conserve resources.</li> + <li>for debugging; the logs are clearer if only one connection is + brought up at a time</li> + </ul> + For a busy and resource-laden production gateway, you likely want "no" + so that connections are brought up in parallel and the whole process + takes less time.</dd> +</dl> + +<p>The example assumes you are at the Reno office and will use IPsec to +Vancouver, New York City and Amsterdam.</p> + +<h2><a name="multitunnel">Multiple tunnels between the same two +gateways</a></h2> + +<p>Consider a pair of subnets, each with a security gateway, connected via +the Internet:</p> +<pre> 192.168.100.0/24 left subnet + | + 192.168.100.1 + North Gateway + 101.101.101.101 left + | + 101.101.101.1 left next hop + [Internet] + 202.202.202.1 right next hop + | + 202.202.202.202 right + South gateway + 192.168.200.1 + | + 192.168.200.0/24 right subnet</pre> + +<p>A tunnel specification such as:</p> +<pre>conn northnet-southnet + left=101.101.101.101 + leftnexthop=101.101.101.1 + leftsubnet=192.168.100.0/24 + leftfirewall=yes + right=202.202.202.202 + rightnexthop=202.202.202.1 + rightsubnet=192.168.200.0/24 + rightfirewall=yes</pre> +will allow machines on the two subnets to talk to each other. You might test +this by pinging from polarbear (192.168.100.7) to penguin (192.168.200.5). + +<p>However, <strong>this does not cover other traffic you might want to +secure</strong>. To handle all the possibilities, you might also want these +connection descriptions:</p> +<pre>conn northgate-southnet + left=101.101.101.101 + leftnexthop=101.101.101.1 + right=202.202.202.202 + rightnexthop=202.202.202.1 + rightsubnet=192.168.200.0/24 + rightfirewall=yes + +conn northnet-southgate + left=101.101.101.101 + leftnexthop=101.101.101.1 + leftsubnet=192.168.100.0/24 + leftfirewall=yes + right=202.202.202.202 + rightnexthop=202.202.202.1</pre> + +<p>Without these, neither gateway can do IPsec to the remote subnet. There is +no IPsec tunnel or eroute set up for the traffic.</p> + +<p>In our example, with the non-routable 192.168.* addresses used, packets +would simply be discarded. In a different configuration, with routable +addresses for the remote subnet, <strong>they would be sent +unencrypted</strong> since there would be no IPsec eroute and there would be +a normal IP route.</p> + +<p>You might also want:</p> +<pre>conn northgate-southgate + left=101.101.101.101 + leftnexthop=101.101.101.1 + right=202.202.202.202 + rightnexthop=202.202.202.1</pre> + +<p>This is required if you want the two gateways to speak IPsec to each +other.</p> + +<p>This requires a lot of duplication of details. Judicious use of +<var>also=</var> and <var>include</var> can reduce this problem.</p> + +<p>Note that, while FreeS/WAN supports all four tunnel types, not all +implementations do. In particular, some versions of Windows 2000 and the +freely downloadable version of PGP provide only "client" functionality. You +cannot use them as gateways with a subnet behind them. To get that +functionality, you must upgrade to Windows 2000 server or the commercially +available PGP products.</p> + +<h3><a name="advroute">One tunnel plus advanced routing</a></h3> +It is also possible to use the new routing features in 2.2 and later kernels +to avoid most needs for multple tunnels. Here is one mailing list message on +the topic: +<pre>Subject: Re: linux-ipsec: IPSec packets not entering tunnel? + Date: Mon, 20 Nov 2000 + From: Justin Guyett <jfg@sonicity.com> + +On Mon, 20 Nov 2000, Claudia Schmeing wrote: + +> Right Left +> "home" "office" +> 10.92.10.0/24 ---- 24.93.85.110 ========= 216.175.164.91 ---- 10.91.10.24/24 +> +> I've created all four tunnels, and can ping to test each of them, +> *except* homegate-officenet. + +I keep wondering why people create all four tunnels. Why not route +traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2? +And 99% of the time you don't need to access "office" directly, which +means you can eliminate all but the subnet<->subnet connection.</pre> +and FreeS/WAN technical lead Henry Spencer's comment: +<pre>> I keep wondering why people create all four tunnels. Why not route +> traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2? + +This is feasible, given some iproute2 attention to source addresses, but +it isn't something we've documented yet... (partly because we're still +making some attempt to support 2.0.xx kernels, which can't do this, but +mostly because we haven't caught up with it yet). + +> And 99% of the time you don't need to access "office" directly, which +> means you can eliminate all but the subnet<->subnet connection. + +Correct in principle, but people will keep trying to ping to or from the +gateways during testing, and sometimes they want to run services on the +gateway machines too.</pre> + + +<!-- Is this in the right spot in this document? --> +<H2><A name="opp.gate">An Opportunistic Gateway</A></H2> + +<H3>Start from full opportunism</H3> + +<P>Full opportunism +allows you to initiate and receive opportunistic connections on your +machine. The remaining instructions in this section assume +you have first set up full opportunism on your gateway using +<A HREF="quickstart.html#opp.incoming">these instructions</A>. +Both sets of instructions require mailing DNS records to your ISP. Collect +DNS records for both the gateway (above) and the +subnet nodes (below) before contacting your ISP.</P> + + +<H3>Reverse DNS TXT records for each protected machine</H3> + +<P>You need these so that your Opportunistic peers can: +<UL> +<LI>discover the gateway's address, knowing only the IP address + that packets are bound for</LI> +<LI>verify that the gateway is authorised to encrypt for that endpoint</LI> +</UL> + +<P>On the gateway, generate a TXT record with: +<PRE> ipsec showhostkey --txt 192.0.2.11</PRE> +<P>Use your gateway address in place of 192.0.2.11.</P> + +<P>You should see (keys are trimmed for clarity throughout our example):</P> +<PRE> ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000 + IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"</PRE> + +<P><B>This MUST BE the same key as in your gateway's TXT record, or nothing +will work.</B></P> + +<P>In a text file, make one copy of this TXT record for each subnet + node:</P> +<PRE> ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000 + IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/" + + ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000 + IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/" + + ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000 + IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"</PRE> + +<P>Above each entry, insert a line like this:</P> +<PRE> 98.2.0.192.in-addr.arpa. IN PTR arthur.example.com.</PRE> + +<P>It must include:</P> +<UL> +<LI>The subnet node's address in reverse map format. For example, 192.0.2.120 +becomes <VAR>120.2.0.192.in-addr.arpa.</VAR>. Note the final period.</LI> +<LI><VAR>IN PTR</VAR></LI> +<LI>The node's name, ie. <VAR>arthur.example.com.</VAR>. Note +the final period.</LI> +</UL> + +<P>The result will be a file of TXT records, like this:</P> +<PRE> 98.2.0.192.in-addr.arpa. IN PTR arthur.example.com. + ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000 + IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/" + + 99.2.0.192.in-addr.arpa. IN PTR ford.example.com. + ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000 + IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/" + + 100.2.0.192.in-addr.arpa. IN PTR trillian.example.com. + ; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000 + IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"</PRE> + + +<H3>Publish your records</H3> + +<P>Ask your ISP to publish all the reverse DNS records you have collected. +There may be a delay of up to 48 hours as the records propagate.</P> + + +<H3>...and test them</H3> + +<P>Check a couple of records with commands like this one:</P> + +<PRE> ipsec verify --host ford.example.com + ipsec verify --host trillian.example.com</PRE> + +<P>The <var>verify</var> command checks for TXT records for both the +subnet host and its gateway. You should see output like:</P> +<PRE> ... + Looking for TXT in reverse map: 99.2.0.192.in-addr.arpa [OK] + ... + Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK] + ... + Looking for TXT in reverse map: 100.2.0.192.in-addr.arpa [OK] + ... + Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK] + ...</PRE> +<H3>No Configuration Needed</H3> + +<P>FreeS/WAN 2.x ships with a built-in, automatically +enabled OE connection <VAR>conn packetdefault</VAR> +which applies OE, if possible, to all outbound traffic routed +through the FreeS/WAN box. + +The +<A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5) manual</A> +describes this connection in detail. +While the effect is much the same as <VAR>private-or-clear</VAR>, +the implementation is different: notably, it does not use policy +groups.</P> + +<P>You can create more complex OE configurations +for traffic forwarded through a FreeS/WAN box, as explained in our +<A HREF="policygroups.html#policygroups">policy groups document</A>, +or disable OE using +<A HREF="policygroups.html#disable_policygroups">these instructions</A>.</P> + + + +<h2><a name="extruded.config">Extruded Subnets</a></h2> + +<p>What we call <a href="glossary.html#extruded">extruded subnets</a> are a +special case of <a href="glossary.html#VPN.gloss">VPNs</a>.</p> + +<p>If your buddy has some unused IP addresses, in his subnet far off at the +other side of the Internet, he can loan them to you... provided that the +connection between you and him is fast enough to carry all the traffic +between your machines and the rest of the Internet. In effect, he "extrudes" +a part of his address space over the network to you, with your Internet +traffic appearing to originate from behind his Internet gateway.</p> + +<p>As far as the Internet is concerned, your new extruded net is behind your +buddy's gateway. You route all your packets for the Internet at large +out his gateway, and receive return packets the same way. You route your +local packets locally.</p> + +<p>Suppose your friend has a.b.c.0/24 and wants to give you a.b.c.240/28. The +initial situation is:</p> +<pre> subnet gateway Internet + a.b.c.0/24 a.b.c.1 p.q.r.s</pre> +where anything from the Internet destined for any machine in a.b.c.0/24 is +routed via p.q.r.s and that gateway knows what to do from there. + +<p>Of course it is quite normal for various smaller subnets to exist behind +your friend's gateway. For example, your friend's company might have +a.b.c.16/28=development, a.b.c.32/28=marketing and so on. The Internet +neither knows not cares about this; it just delivers packets to the p.q.r.s +and lets the gateway do whatever needs to be done from there.</p> + +<p>What we want to do is take a subnet, perhaps a.b.c.240/28, out of your +friend's physical location <em>while still having your friend's gateway route +to it</em>. As far as the Internet is concerned, you remain behind that +gateway.</p> +<pre> subnet gateway Internet your gate extruded + + a.b.c.0/24 a.b.c.1 p.q.r.s d.e.f.g a.b.c.240/28 + + ========== tunnel ==========</pre> + +<p>The extruded addresses have to be a complete subnet.</p> + +<p>In our example, the friend's security gateway is also his Internet +gateway, but this is not necessary. As long as all traffic from the Internet +to his addresses passes through the Internet gate, the security gate could be +a machine behind that. The IG would need to route all traffic for the +extruded subnet to the SG, and the SG could handle the rest.</p> + +<p>First, configure your subnet using the extruded addresses. Your security +gateway's interface to your subnet needs to have an extruded address +(possibly using a Linux <a href="glossary.html#virtual">virtual +interface</a>, if it also has to have a different address). Your gateway +needs to have a route to the extruded subnet, pointing to that interface. The +other machines at your site need to have addresses in that subnet, and +default routes pointing to your gateway.</p> + +<p>If any of your friend's machines need to talk to the extruded subnet, +<em>they</em> need to have a route for the extruded subnet, pointing at his +gateway.</p> + +<p>Then set up an IPsec subnet-to-subnet tunnel between your gateway and his, +with your subnet specified as the extruded subnet, and his subnet specified +as "0.0.0.0/0".</p> + +<p>The tunnel description should be:</p> +<pre>conn extruded + left=p.q.r.s + leftsubnet=0.0.0.0/0 + right=d.e.f.g + rightsubnet=a.b.c.0/28</pre> + +<p>If either side was doing firewalling for the extruded subnet before the +IPsec connection is set up, you'll need to poke holes in your +<A HREF="firewall.html#firewall">firewall</A> to allow packets through. +</p> + +<p>And it all just works. Your SG routes traffic for 0.0.0.0/0 -- that is, +the whole Internet -- through the tunnel to his SG, which then sends it +onward as if it came from his subnet. When traffic for the extruded subnet +arrives at his SG, it gets sent through the tunnel to your SG, which passes +it to the right machine.</p> + +<p>Remember that when ipsec_manual or ipsec_auto takes a connection down, it +<em>does not undo the route</em> it made for that connection. This lets you +take a connection down and bring up a new one, or a modified version of the +old one, without having to rebuild the route it uses and without any risk of +packets which should use IPsec accidentally going out in the clear. Because +the route always points into KLIPS, the packets will always go there. Because +KLIPS temporarily has no idea what to do with them (no eroute for them), they +will be discarded.</p> + +<p>If you <em>do</em> want to take the route down, this is what the "unroute" +operation in manual and auto is for. Just do an unroute after doing the +down.</p> + +<p>Note that the route for a connection may have replaced an existing +non-IPsec route. Nothing in Linux FreeS/WAN will put that pre-IPsec route +back. If you need it back, you have to create it with the route command.</p> + +<h2><a name="roadvirt">Road Warrior with virtual IP address</a></h2> + +<p>Please note that <A HREF="http://www.freeswan.ca/download.php">Super +FreeS/WAN</A> now features DHCP-over-IPsec, which is an alternate procedure +for Virtual IP address assignment. +<p> + +<p>Here is a mailing list message about another way to configure for road +warrior support:</p> +<pre>Subject: Re: linux-ipsec: understanding the vpn + Date: Thu, 28 Oct 1999 10:43:22 -0400 + From: Irving Reid <irving@nevex.com> + +> local-------linux------internet------mobile +> LAN box user +> ... + +> now when the mobile user connects to the linux box +> it is given a virtual IP address, i have configured it to +> be in the 10.x.x.x range. mobile user and linux box +> have a tunnel between them with these IP addresses. + +> Uptil this all is fine. + +If it is possible to configure your mobile client software *not* to +use a virtual IP address, that will make your life easier. It is easier +to configure FreeS/WAN to use the actual address the mobile user gets +from its ISP. + +Unfortunately, some Windows clients don't let you choose. + +> what i would like to know is that how does the mobile +> user communicate with other computers on the local +> LAN , of course with the vpn ? + +> what IP address should the local LAN +> computers have ? I guess their default gateway +> should be the linux box ? and does the linux box need +> to be a 2 NIC card box or one is fine. + +As someone else stated, yes, the Linux box would usually be the default +IP gateway for the local lan. + +However... + +If you mobile user has software that *must* use a virtual IP address, +the whole picture changes. Nobody has put much effort into getting +FreeS/WAN to play well in this environment, but here's a sketch of one +approach: + +Local Lan 1.0.0.0/24 + | + +- Linux FreeS/WAN 1.0.0.2 + | + | 1.0.0.1 + Router + | 2.0.0.1 + | +Internet + | + | 3.0.0.1 +Mobile User + Virtual Address: 1.0.0.3 + +Note that the Local Lan network (1.0.0.x) can be registered, routable +addresses. + +Now, the Mobile User sets up an IPSec security association with the +Linux box (1.0.0.2); it should ESP encapsulate all traffic to the +network 1.0.0.x **EXCEPT** UDP port 500. 500/udp is required for the key +negotiation, which needs to work outside of the IPSec tunnel. + +On the Linux side, there's a bunch of stuff you need to do by hand (for +now). FreeS/WAN should correctly handle setting up the IPSec SA and +routes, but I haven't tested it so this may not work... + +The FreeS/WAN conn should look like: + +conn mobile + right=1.0.0.2 + rightsubnet=1.0.0.0/24 + rightnexthop=1.0.0.1 + left=0.0.0.0 # The infamous "road warrior" + leftsubnet=1.0.0.3/32 + +Note that the left subnet contains *only* the remote host's virtual +address. + +Hopefully the routing table on the FreeS/WAN box ends up looking like +this: + +% netstat -rn +Kernel IP routing table +Destination Gateway Genmask Flags MSS Window irtt Iface +1.0.0.0 0.0.0.0 255.255.255.0 U 1500 0 0 eth0 +127.0.0.0 0.0.0.0 255.0.0.0 U 3584 0 0 lo +0.0.0.0 1.0.0.1 0.0.0.0 UG 1500 0 0 eth0 +1.0.0.3 1.0.0.1 255.255.255.255 UG 1433 0 0 ipsec0 + +So, if anybody sends a packet for 1.0.0.3 to the Linux box, it should +get bundled up and sent through the tunnel. To get the packets for +1.0.0.3 to the Linux box in the first place, you need to use "proxy +ARP". + +How this works is: when a host or router on the local Ethernet segment +wants to send a packet to 1.0.0.3, it sends out an Ethernet level +broadcast "ARP request". If 1.0.0.3 was on the local LAN, it would +reply, saying "send IP packets for 1.0.0.3 to my Ethernet address". + +Instead, you need to set up the Linux box so that _it_ answers ARP +requests for 1.0.0.3, even though that isn't its IP address. That +convinces everyone else on the lan to send 1.0.0.3 packets to the Linux +box, where the usual FreeS/WAN processing and routing take over. + +% arp -i eth0 -s 1.0.0.3 -D eth0 pub + +This says, if you see an ARP request on interface eth0 asking for +1.0.0.3, respond with the Ethernet address of interface eth0. + +Now, as I said at the very beginning, if it is *at all* possible to +configure your client *not* to use the virtual IP address, you can avoid +this whole mess.</pre> + +<h2><a name="dynamic">Dynamic Network Interfaces</a></h2> + +<p>Sometimes you have to cope with a situation where the network interface(s) +aren't all there at boot. The common example is notebooks with PCMCIA.</p> + +<h3><a name="basicdyn">Basics</a></h3> + +<p>The key issue here is that the <var>config setup</var> section of the +<var>/etc/ipsec.conf</var> configuration file lists the connection between +ipsecN and hardware interfaces, in the <var>interfaces=</var> variable. At +any time when <var>ipsec setup start</var> or <var>ipsec setup restart</var> +is run this variable <strong>must</strong> correspond to the current real +situation. More precisely, it <strong>must not</strong> mention any hardware +interfaces which don't currently exist. The difficulty is that an <var>ipsec +setup start</var> command is normally run at boot time so interfaces that are +not up then are mis-handled.</p> + +<h3><a name="bootdyn">Boot Time</a></h3> + +<p>Normally, an <var>ipsec setup start</var> is run at boot time. However, if +the hardware situation at boot time is uncertain, one of two things must be +done.</p> +<ul> + <li>One possibility is simply not to have IPsec brought up at boot time. To + do this: + <pre> chkconfig --level 2345 ipsec off</pre> + That's for modern Red Hats or other Linuxes with chkconfig. Systems which + lack this will require fiddling with symlinks in /etc/rc.d/rc?.d or the + equivalent.</li> + <li>Another possibility is to bring IPsec up with no interfaces, which is + less aesthetically satisfying but simpler. Just put + <pre> interfaces=</pre> + in the configuration file. KLIPS and Pluto will be started, but won't do + anything.</li> +</ul> + +<h3><a name="changedyn">Change Time</a></h3> + +<p>When the hardware *is* in place, IPsec has to be made aware of it. Someday +there may be a nice way to do this.</p> + +<p>Right now, the way to do it is to fix the <var>/etc/ipsec.conf</var> file +appropriately, so <var>interfaces</var> reflects the new situation, and then +restart the IPsec subsystem. This does break any existing IPsec +connections.</p> + +<p>If IPsec wasn't brought up at boot time, do</p> +<pre> ipsec setup start</pre> +while if it was, do +<pre> ipsec setup restart</pre> +which won't be as quick. + +<p>If some of the hardware is to be taken out, before doing that, amend the +configuration file so interfaces no longer includes it, and do</p> +<pre> ipsec setup restart</pre> + +<p>Again, this breaks any existing connections.</p> + +<h2><a name="unencrypted">Unencrypted tunnels</a></h2> + +<p>Sometimes you might want to create a tunnel without encryption. Often this +is a bad idea, even if you have some data which need not be private. See this +<a href="ipsec.html#traffic.resist">discussion</a>.</p> + +<p>The IPsec protocols provide two ways to do build such tunnels:</p> +<dl> + <dt>using ESP with null encryption</dt> + <dd>not supported by FreeS/WAN</dd> + <dt>using <a href="glossary.html#AH">AH</a> without <a + href="glossary.html#ESP">ESP</a></dt> + <dd>supported for manually keyed connections</dd> + <dd>possible with explicit commands via <a + href="manpage.d/ipsec_whack.8.html">ipsec_whack(8)</a> (see this <a + href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00190.html">list + message</a>)</dd> + <dd>not supported in the <a + href="manpage.d/ipsec_auto.8.html">ipsec_auto(8)</a> scripts.</dd> +</dl> +One situation in which this comes up is when otherwise some data would be +encrypted twice. Alice wants a secure tunnel from her machine to Bob's. Since +she's behind one security gateway and he's behind another, part of the tunnel +that they build passes through the tunnel that their site admins have built +between the gateways. All of Alice and Bob's messages are encrypted twice. + +<p>There are several ways to handle this.</p> +<ul> + <li>Just accept the overhead of double encryption. The site admins might + choose this if any of the following apply: + <ul> + <li>policy says encrypt everything (usually, it should)</li> + <li>they don't entirely trust Alice and Bob (usually, if they don't + have to, they shouldn't)</li> + <li>if they don't feel the saved cycles are worth the time they'd need + to build a non-encrypted tunnel for Alice and Bob's packets (often, + they aren't)</li> + </ul> + </li> + <li>Use a plain IP-in-IP tunnel. These are not well documented. A good + starting point is in the Linux kernel source tree, in + /usr/src/linux/drivers/net/README.tunnel.</li> + <li>Use a manually-keyed AH-only tunnel.</li> +</ul> + +<p>Note that if Alice and Bob want end-to-end security, they must build a +tunnel end-to-end between their machines or use some other end-to-end tool +such as PGP or SSL that suits their data. The only question is whether the +admins build some special unencrypted tunnel for those already-encrypted +packets.</p> +</body> +</html> diff --git a/doc/src/background.html b/doc/src/background.html new file mode 100644 index 000000000..e25b9da03 --- /dev/null +++ b/doc/src/background.html @@ -0,0 +1,376 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN background</title> + <meta name="keywords" content="Linux, IPSEC, VPN, security, FreeSWAN"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: background.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="background">Linux FreeS/WAN background</a></h1> + +<p>This section discusses a number of issues which have three things in +common:</p> +<ul> + <li>They are not specifically FreeS/WAN problems</li> + <li>You may have to understand them to get FreeS/WAN working right</li> + <li>They are not simple questions</li> +</ul> + +<p>Grouping them here lets us provide the explanations some users will need +without unduly complicating the main text.</p> + +<p>The explanations here are intended to be adequate for FreeS/WAN purposes +(please comment to the <a href="mail.html">users mailing list</a> if you +don't find them so), but they are not trying to be complete or definitive. If +you need more information, see the references provided in each section.</p> + +<h2><a name="dns.background">Some DNS background</a></h2> + +<p><a href="glossary.html#carpediem">Opportunistic encryption</a> requires +that the gateway systems be able to fetch public keys, and other +IPsec-related information, from each other's DNS (Domain Name Service) +records.</p> + +<p><a href="glossary.html#DNS">DNS</a> is a distributed database that maps +names to IP addresses and vice versa.</p> + +<p>Much good reference material is available for DNS, including:</p> +<ul> + <li>the <a href="http://www.linuxdoc.org/HOWTO/DNS-HOWTO.html">DNS + HowTo</a></li> + <li>the standard <a href="biblio.html#DNS.book">DNS reference</a> book</li> + <li><a href="http://www.linuxdoc.org/LDP/nag2/index.html">Linux Network + Administrator's Guide</a></li> + <li><a + href="http://www.nominum.com/resources/whitepapers/bind-white-paper.html">BIND + overview</a></li> + <li><a + href="http://www.nominum.com/resources/documentation/Bv9ARM.pdf">BIND 9 + Administrator's Reference</a></li> +</ul> + +<p>We give only a brief overview here, intended to help you use DNS for +FreeS/WAN purposes.</p> + +<h3><a name="forward.reverse">Forward and reverse maps</a></h3> + +<p>Although the implementation is distributed, it is often useful to speak of +DNS as if it were just two enormous tables:</p> +<ul> + <li>the forward map: look up a name, get an IP address</li> + <li>the reverse map: look up an IP address, get a name</li> +</ul> + +<p>Both maps can optionally contain additional data. For opportunistic +encryption, we insert the data need for IPsec authentication.</p> + +<p>A system named gateway.example.com with IP address 10.20.30.40 should have +at least two DNS records, one in each map:</p> +<dl> + <dt>gateway.example.com. IN A 10.20.30.40</dt> + <dd>used to look up the name and get an IP address</dd> + <dt>40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.</dt> + <dd>used for reverse lookups, looking up an address to get the associated + name. Notice that the digits here are in reverse order; the actual + address is 10.20.30.40 but we use 40.30.20.10 here.</dd> +</dl> + +<h3>Hierarchy and delegation</h3> + +<p>For both maps there is a hierarchy of DNS servers and a system of +delegating authority so that, for example:</p> +<ul> + <li>the DNS administrator for example.com can create entries of the form + <var>name</var>.example.com</li> + <li>the example.com admin cannot create an entry for counterexample.com; + only someone with authority for .com can do that</li> + <li>an admin might have authority for 20.10.in-addr.arpa.</li> + <li>in either map, authority can be delegated + <ul> + <li>the example.com admin could give you authority for + westcoast.example.com</li> + <li>the 20.10.in-addr.arpa admin could give you authority for + 30.20.10.in-addr.arpa</li> + </ul> + </li> +</ul> + +<p>DNS zones are the units of delegation. There is a hierarchy of zones.</p> + +<h3>Syntax of DNS records</h3> + +<p>Returning to the example records:</p> +<pre> gateway.example.com. IN A 10.20.30.40 + 40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.</pre> + +<p>some syntactic details are:</p> +<ul> + <li>the IN indicates that these records are for <strong>In</strong>ternet + addresses</li> + <li>The final periods in '.com.' and '.arpa.' are required. They indicate + the root of the domain name system.</li> +</ul> + +<p>The capitalised strings after IN indicate the type of record. Possible +types include:</p> +<ul> + <li><strong>A</strong>ddress, for forward lookups</li> + <li><strong>P</strong>oin<strong>T</strong>e<strong>R</strong>, for reverse + lookups</li> + <li><strong>C</strong>anonical <strong>NAME</strong>, records to support + aliasing, multiple names for one address</li> + <li><strong>M</strong>ail e<strong>X</strong>change, used in mail + routing</li> + <li><strong>SIG</strong>nature, used in <a href="glossary.html#SDNS">secure + DNS</a></li> + <li><strong>KEY</strong>, used in <a href="glossary.html#SDNS">secure + DNS</a></li> + <li><strong>T</strong>e<strong>XT</strong>, a multi-purpose record type</li> +</ul> + +<p>To set up for opportunistic encryption, you add some TXT records +to your DNS data. Details are in our <a href="quickstart.html">quickstart</a> +document.</p> + +<h3>Cacheing, TTL and propagation delay</h3> + +<p>DNS information is extensively cached. With no caching, a lookup by your +system of "www.freeswan.org" might involve:</p> +<ul> + <li>your system asks your nameserver for "www.freeswan.org"</li> + <li>local nameserver asks root server about ".org", gets reply</li> + <li>local nameserver asks .org nameserver about "freeswan.org", gets + reply</li> + <li>local nameserver asks freeswan.org nameserver about "www.freeswan.org", + gets reply</li> +</ul> + +<p>However, this can be a bit inefficient. For example, if you are in the +Phillipines, the closest a root server is in Japan. That might send you to a +.org server in the US, and then to freeswan.org in Holland. If everyone did +all those lookups every time they clicked on a web link, the net would grind +to a halt.</p> + +<p>Nameservers therefore cache information they look up. When you click on +another link at www.freeswan.org, your local nameserver has the IP address +for that server in its cache, and no further lookups are required. </p> + +<p>Intermediate results are also cached. If you next go to +lists.freeswan.org, your nameserver can just ask the freeswan.org nameserver +for that address; it does not need to query the root or .org nameservers +because it has a cached address for the freeswan.org zone server.</p> + +<p>Of course, like any cacheing mechanism, this can create problems of +consistency. What if the administrator for freeswan.org changes the IP +address, or the authentication key, for www.freeswan.org? If you use old +information from the cache, you may get it wrong. On the other hand, you +cannot afford to look up fresh information every time. Nor can you expect the +freeswan.org server to notify you; that isn't in the protocols.</p> + +<p>The solution that is in the protocols is fairly simple. Cacheable records +are marked with Time To Live (TTL) information. When the time expires, the +caching server discards the record. The next time someone asks for it, the +server fetches a fresh copy. Of course, a server may also discard records +before their TTL expires if it is running out of cache space.</p> + +<p>This implies that there will be some delay before the new version of a +changed record propagates around the net. Until the TTLs on all copies of the +old record expire, some users will see it because that is what is in their +cache. Other users may see the new record immediately because they don't have +an old one cached.</p> + +<h2><a name="MTU.trouble">Problems with packet fragmentation</a></h2> + +<p>It seems, from mailing list reports, to be moderately common for problems +to crop up in which small packets pass through the IPsec tunnels just fine +but larger packets fail.</p> + +<p>These problems are caused by various devices along the way mis-handling +either packet fragments or <a href="glossary.html#pathMTU">path MTU +discovery</a>.</p> + +<p>IPsec makes packets larger by adding an ESP or AH header. This can tickle +assorted bugs in fragment handling in routers and firewalls, or in path MTU +discovery mechanisms, and cause a variety of symptoms which are both annoying +and, often, quite hard to diagnose.</p> + +<p>An explanation from project technical lead Henry Spencer:</p> +<pre>The problem is IP fragmentation; more precisely, the problem is that the +second, third, etc. fragments of an IP packet are often difficult for +filtering mechanisms to classify. + +Routers cannot rely on reassembling the packet, or remembering what was in +earlier fragments, because the fragments may be out of order or may even +follow different routes. So any general, worst-case filtering decision +pretty much has to be made on each fragment independently. (If the router +knows that it is the only route to the destination, so all fragments +*must* pass through it, reassembly would be possible... but most routers +don't want to bother with the complications of that.) + +All fragments carry roughly the original IP header, but any higher-level +header is (for IP purposes) just the first part of the packet data... so +only the first fragment carries that. So, for example, on examining the +second fragment of a TCP packet, you could tell that it's TCP, but not +what port number it is destined for -- that information is in the TCP +header, which appears in the first fragment only. + +The result of this classification difficulty is that stupid routers and +over-paranoid firewalls may just throw fragments away. To get through +them, you must reduce your MTU enough that fragmentation will not occur. +(In some cases, they might be willing to attempt reassembly, but have very +limited resources to devote to it, meaning that packets must be small and +fragments few in number, leading to the same conclusion: smaller MTU.)</pre> + +<p>In addition to the problem Henry describes, you may also have trouble with +<a href="glossary.html#pathMTU">path MTU discovery</a>.</p> + +<p>By default, FreeS/WAN uses a large <a href="glossary.html#MTU">MTU</a> for +the ipsec device. This avoids some problems, but may complicate others. +Here's an explanation from Claudia:</p> +<pre>Here are a couple of pieces of background information. Apologies if you +have seen these already. An excerpt from one of my old posts: + + An MTU of 16260 on ipsec0 is usual. The IPSec device defaults to this + high MTU so that it does not fragment incoming packets before encryption + and encapsulation. If after IPSec processing packets are larger than 1500, + [ie. the mtu of eth0] then eth0 will fragment them. + + Adding IPSec headers adds a certain number of bytes to each packet. + The MTU of the IPSec interface refers to the maximum size of the packet + before the IPSec headers are added. In some cases, people find it helpful + to set ipsec0's MTU to 1500-(IPSec header size), which IIRC is about 1430. + + That way, the resulting encapsulated packets don't exceed 1500. On most + networks, packets less than 1500 will not need to be fragmented. + +and... (from Henry Spencer) + + The way it *ought* to work is that the MTU advertised by the ipsecN + interface should be that of the underlying hardware interface, less a + pinch for the extra headers needed. + + Unfortunately, in certain situations this breaks many applications. + There is a widespread implicit assumption that the smallest MTUs are + at the ends of paths, not in the middle, and another that MTUs are + never less than 1500. A lot of code is unprepared to handle paths + where there is an "interior minimum" in the MTU, especially when it's + less than 1500. So we advertise a big MTU and just let the resulting + big packets fragment. + +This usually works, but we do get bitten in cases where some intermediate +point can't handle all that fragmentation. We can't win on this one.</pre> + +<p>The MTU can be changed with an <var>overridemtu=</var> statement in the +<var>config setup</var> section of <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf.5</a>.</p> + +<p>For a discussion of MTU issues and some possible solutions using Linux +advanced routing facilities, see the <a +href="http://www.linuxguruz.org/iptables/howto/2.4routing-15.html#ss15.6">Linux +2.4 Advanced Routing HOWTO</a>. + +For a discussion of MTU and NAT (Network Address Translation), see +<A HREF="http://harlech.math.ucla.edu/services/ipsec.html">James Carter's MTU +notes</A>.</p> + +<h2><a name="nat.background">Network address translation (NAT)</a></h2> + +<p><strong>N</strong>etwork <strong>A</strong>ddress +<strong>T</strong>ranslation is a service provided by some gateway machines. +Calling it NAPT (adding the word <strong>P</strong>ort) would be more +precise, but we will follow the widespread usage.</p> + +<p>A gateway doing NAT rewrites the headers of packets it is forwarding, +changing one or more of:</p> +<ul> + <li>source address</li> + <li>source port</li> + <li>destination address</li> + <li>destination port</li> +</ul> + +<p>On Linux 2.4, NAT services are provided by the <a +href="http://netfilter.samba.org">netfilter(8)</a> firewall code. There are +several <a +href="http://netfilter.samba.org/documentation/index.html#HOWTO">Netfilter +HowTos</a> including one on NAT.</p> + +<p>For older versions of Linux, this was referred to as "IP masquerade" and +different tools were used. See this <a +href="http://www.e-infomax.com/ipmasq/">resource page</a>.</p> + +<p>Putting an IPsec gateway behind a NAT gateway is not recommended. See our +<a href="firewall.html#NAT">firewalls document</a>.</p> + +<h3>NAT to non-routable addresses</h3> + +<p>The most common application of NAT uses private <a +href="glossary.html#non-routable">non-routable</a> addresses.</p> + +<p>Often a home or small office network will have:</p> +<ul> + <li>one connection to the Internet</li> + <li>one assigned publicly visible IP address</li> + <li>several machines that all need access to the net</li> +</ul> + +<p>Of course this poses a problem since several machines cannot use one +address. The best solution might be to obtain more addresses, but often this +is impractical or uneconomical.</p> + +<p>A common solution is to have:</p> +<ul> + <li><a href="glossary.html#non-routable">non-routable</a> addresses on the + local network</li> + <li>the gateway machine doing NAT</li> + <li>all packets going outside the LAN rewritten to have the gateway as + their source address</li> +</ul> + +<p>The client machines are set up with reserved <a +href="#non-routable">non-routable</a> IP addresses defined in RFC 1918. The +masquerading gateway, the machine with the actual link to the Internet, +rewrites packet headers so that all packets going onto the Internet appear to +come from one IP address, that of its Internet interface. It then gets all +the replies, does some table lookups and more header rewriting, and delivers +the replies to the appropriate client machines.</p> + +<p>As far as anyone else on the Internet is concerned, the systems behind the +gateway are completely hidden. Only one machine with one IP address is +visible.</p> + +<p>For IPsec on such a gateway, you can entirely ignore the NAT in:</p> +<ul> + <li><a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a></li> + <li>firewall rules affecting your Internet-side interface</li> +</ul> + +<p>Those can be set up exactly as they would be if your gateway had no other +systems behind it.</p> + +<p>You do, however, have to take account of the NAT in firewall rules which +affect packet forwarding.</p> + +<h3>NAT to routable addresses</h3> + +<p>NAT to routable addresses is also possible, but is less common and may +make for rather tricky routing problems. We will not discuss it here. See the +<a href="http://netfilter.samba.org/documentation/index.html#HOWTO">Netfilter +HowTos</a>.</p> +</body> +</html> diff --git a/doc/src/biblio.html b/doc/src/biblio.html new file mode 100644 index 000000000..d84e4c2cb --- /dev/null +++ b/doc/src/biblio.html @@ -0,0 +1,354 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN bibliography</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, bibliography"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: biblio.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="biblio">Bibliography for the Linux FreeS/WAN project</a></h1> + +<p>For extensive bibliographic links, see the <a +href="http://liinwww.ira.uka.de/bibliography/index.html">Collection of +Computer Science Bibliographies</a></p> + +<p>See our <a href="web.html">web links</a> for material available online.</p> +<hr> +<a name="adams">Carlisle Adams and Steve Lloyd <cite>Understanding Public Key +Infrastructure</cite><br> +</a>Macmillan 1999 ISBN 1-57870-166-x + +<p>An overview, mainly concentrating on policy and strategic issues rather +than the technical details. Both authors work for <a +href="glossary.html#PKI">PKI</a> vendor <a +href="http://www.entrust.com/">Entrust</a>.</p> +<hr> +<a name="DNS.book">Albitz, Liu & Loukides <cite>DNS & BIND</cite> 3rd +edition<br> +</a> O'Reilly 1998 ISBN 1-56592-512-2 + +<p>The standard reference on the <a href="glossary.html#DNS">Domain Name +Service</a> and <a href="glossary.html#BIND">Berkeley Internet Name +Daemon</a>.</p> +<hr> +<a name="anderson">Ross Anderson</a>, <cite>Security Engineering - a Guide to +Building Dependable Distributed Systems</cite><br> +Wiley, 2001, ISBN 0471389226 + +<p>Easily the best book for the security professional I have seen. +<strong>Highly recommended</strong>. See the <a +href="http://www.cl.cam.ac.uk/~rja14/book.html">book web page</a>.</p> + +<p>This is quite readable, but Schneier's <a href="#secrets">Secrets and +Lies</a> might be an easier introduction.</p> +<hr> +<a name="puzzle">Bamford <cite>The Puzzle Palace, A report on NSA, Americas's +most Secret Agency</cite><br> +Houghton Mifflin 1982 ISBN 0-395-31286-8</a> +<hr> +Bamford <cite>Body of Secrets</cite> + +<p>The sequel.</p> +<hr> +<a name="bander">David Bander</a>, <cite>Linux Security Toolkit</cite><br> +IDG Books, 2000, ISBN: 0764546902 + +<p>This book has a short section on FreeS/WAN and includes Caldera Linux on +CD.</p> +<hr> +<a name="CZR">Chapman, Zwicky & Russell</a>, <cite>Building Internet +Firewalls</cite><br> +O'Reilly 1995 ISBN 1-56592-124-0 +<hr> +<a name="firewall.book">Cheswick and Bellovin</a> <cite>Firewalls and +Internet Security: Repelling the Wily Hacker</cite><br> +Addison-Wesley 1994 ISBN 0201633574 + +<p>A fine book on firewalls in particular and security in general from two of +AT&T's system adminstrators.</p> + +<p>Bellovin has also done a number of <a href="web.html#papers">papers</a> on +IPsec and co-authored a <a href="intro.html#applied">paper</a> on a large +FreeS/WAN application.</p> +<hr> +<a name="comer">Comer <cite>Internetworking with TCP/IP</cite><br> +Prentice Hall</a> +<ul> + <li>Vol. I: Principles, Protocols, & Architecture, 3rd Ed. 1995 + ISBN:0-13-216987-8</li> + <li>Vol. II: Design, Implementation, & Internals, 2nd Ed. 1994 + ISBN:0-13-125527-4</li> + <li>Vol. III: Client/Server Programming & Applications + <ul> + <li>AT&T TLI Version 1994 ISBN:0-13-474230-3</li> + <li>BSD Socket Version 1996 ISBN:0-13-260969-X</li> + <li>Windows Sockets Version 1997 ISBN:0-13-848714-6</li> + </ul> + </li> +</ul> + +<p>If you need to deal with the details of the network protocols, read either +this series or the <a href="#stevens">Stevens and Wright</a> series before +you start reading the RFCs.</p> +<hr> +<a name="diffie">Diffie and Landau</a> <cite>Privacy on the Line: The +Politics of Wiretapping and Encryption</cite><br> +MIT press 1998 ISBN 0-262-04167-7 (hardcover) or 0-262-54100-9<br> + +<hr> +<a name="d_and_hark">Doraswamy and Harkins <cite>IP Sec: The New Security +Standard for the Internet, Intranets and Virtual Private Networks</cite><br> +Prentice Hall 1999 ISBN: 0130118982</a> +<hr> +<a name="EFF"> Electronic Frontier Foundation <cite>Cracking DES: Secrets of +Encryption Research, Wiretap Politics and Chip Design</cite><br> +</a> O'Reilly 1998 ISBN 1-56592-520-3 + +<p>To conclusively demonstrate that DES is inadequate for continued use, the +<a href="glossary.html#EFF">EFF</a> built a machine for just over $200,000 +that breaks DES encryption in under five days on average, under nine in the +worst case.</p> + +<p>The book provides details of their design and, perhaps even more +important, discusses why they felt the project was necessary. Recommended for +anyone interested in any of the three topics mentioned in the subtitle.</p> + +<p>See also the <a href="http://www.eff.org/descracker.html"> EFF page on +this project </a> and our discussion of <a +href="politics.html#desnotsecure">DES insecurity</a>.</p> +<hr> +Martin Freiss <cite>Protecting Networks with SATAN</cite><br> +O'Reilly 1998 ISBN 1-56592-425-8<br> +translated from a 1996 work in German + +<p>SATAN is a Security Administrator's Tool for Analysing Networks. This book +is a tutorial in its use.</p> +<hr> +Gaidosch and Kunzinger<cite> A Guide to Virtual Private Networks</cite><br> +Prentice Hall 1999 ISBN: 0130839647 +<hr> +<a name="Garfinkel">Simson Garfinkel</a> <cite>Database Nation: the death of +privacy in the 21st century</cite><br> +O'Reilly 2000 ISBN 1-56592-653-6 + +<p>A thoughtful and rather scary book.</p> +<hr> +<a name="PGP">Simson Garfinkel</a> <cite>PGP: Pretty Good Privacy</cite><br> +O'Reilly 1995 ISBN 1-56592-098-8 + +<p>An excellent introduction and user manual for the <a +href="glossary.html#PGP">PGP</a> email-encryption package. PGP is a good +package with a complex and poorly-designed user interface. This book or one +like it is a must for anyone who has to use it at length.</p> + +<p>The book covers using PGP in Unix, PC and Macintosh environments, plus +considerable background material on both the technical and political issues +around cryptography.</p> + +<p>The book is now seriously out of date. It does not cover recent +developments such as commercial versions since PGP 5, the Open PGP standard +or GNU PG..</p> +<hr> +<a name="practical">Garfinkel and Spafford</a> <cite>Practical Unix +Security</cite><br> +O'Reilly 1996 ISBN 1-56592-148-8 + +<p>A standard reference.</p> + +<p>Spafford's web page has an excellent collection of<a +href="http://www.cs.purdue.edu/coast/hotlist"> crypto and security +links</a>.</p> +<hr> +<a name="Kahn">David Kahn</a> <cite>The Codebreakers: the Comprehensive +History of Secret Communications from Ancient Times to the Internet</cite><br> +second edition Scribner 1996 ISBN 0684831309 + +<p>A history of codes and code-breaking from ancient Egypt to the 20th +century. Well-written and exhaustively researched. <strong>Highly +recommended</strong>, even though it does not have much on computer +cryptography.</p> +<hr> +David Kahn <cite>Seizing the Enigma, The Race to Break the German U-Boat +codes, 1939-1943</cite><br> +Houghton Mifflin 1991 ISBN 0-395-42739-8 +<hr> +<a name="kirch">Olaf Kirch</a> <cite>Linux Network Administrator's +Guide</cite><br> +O'Reilly 1995 ISBN 1-56592-087-2 + +<p>Now becoming somewhat dated in places, but still a good introductory book +and general reference.</p> +<hr> +<a name="LinVPN">Kolesnikov and Hatch</a>, <cite>Building Linux Virtual +Private Networks (VPNs)</cite><br> +New Riders 2002 + +<p>This has had a number of favorable reviews, including <a +href="http://www.slashdot.org/article.pl?sid=02/02/27/0115214&mode=thread&tid=172">this +one</a> on Slashdot. The book has a <a +href="http://www.buildinglinuxvpns.net/">web site</a>.</p> +<hr> +<a name="RFCs">Pete Loshin <cite>Big Book of IPsec RFCs</cite><br> +Morgan Kaufmann 2000 ISBN: 0-12-455839-9</a> +<hr> +<a name="crypto">Steven Levy <cite>Crypto: How the Code Rebels Beat the +Government -- Saving Privacy in the Digital Age</cite></a><br> +Penguin 2001, ISBN 0-670--85950-8 + +<p><strong>Highly recommended</strong>. A fine history of recent (about +1970-2000) developments in the field, and the related political +controversies. FreeS/WAN project founder and leader John Gilmore appears +several times.</p> + +<p>The book does not cover IPsec or FreeS/WAN, but this project is very much +another battle in the same war. See our discussion of the <a +href="politics.html">politics</a>.</p> +<hr> +<a name="GTR">Matyas, Anderson et al.</a> <cite>The Global Trust +Register</cite><br> +Northgate Consultants Ltd 1998 ISBN: 0953239705<br> +hard cover edition MIT Press 1999 ISBN 0262511053 + +<p>From<a href="http://www.cl.cam.ac.uk/Research/Security/Trust-Register"> +their web page:</a></p> + +<blockquote> + This book is a register of the fingerprints of the world's most important + public keys; it implements a top-level certification authority (CA) using + paper and ink rather than in an electronic system.</blockquote> +<hr> +<a name="handbook">Menezies, van Oorschot and Vanstone <cite>Handbook of +Applied Cryptography</cite></a><br> +CRC Press 1997<br> +ISBN 0-8493-8523-7 + +<p>An excellent reference. Read <a href="#schneier">Schneier</a> before +tackling this.</p> +<hr> +Michael Padlipsky <cite>Elements of Networking Style</cite><br> +Prentice-Hall 1985 ISBN 0-13-268111-0 or 0-13-268129-3 + +<p>Probably <strong>the funniest technical book ever written</strong>, this +is a vicious but well-reasoned attack on the OSI "seven layer model" and all +that went with it. Several chapters of it are also available as RFCs 871 to +875.</p> +<hr> +<a name="matrix">John S. Quarterman</a> <cite>The Matrix: Computer Networks +and Conferencing Systems Worldwide</cite><br> +Digital Press 1990 ISBN 155558-033-5<br> +Prentice-Hall ISBN 0-13-565607-9 + +<p>The best general treatment of computer-mediated communication we have +seen. It naturally has much to say about the Internet, but also covers UUCP, +Fidonet and so on.</p> +<hr> +<a name="ranch">David Ranch</a> <cite>Securing Linux Step by Step</cite><br> +SANS Institute, 1999 + +<p><a href="http://www.sans.org/">SANS</a> is a respected organisation, this +guide is part of a well-known series, and Ranch has previously written the +useful <a +href=" http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#trinityos">Trinity +OS</a> guide to securing Linux, so my guess would be this is a pretty good +book. I haven't read it yet, so I'm not certain. It can be ordered online +from <a href="http://www.sans.org/">SANS</a>.</p> + +<p>Note (Mar 1, 2002): a new edition with different editors in the works. +Expect it this year.</p> +<hr> +<a name="schneier">Bruce Schneier</a> <cite>Applied Cryptography, Second +Edition</cite><br> +John Wiley & Sons, 1996<br> +ISBN 0-471-12845-7 hardcover<br> +ISBN 0-471-11709-9 paperback + +<p>A standard reference on computer cryptography. For more recent essays, see +the <a href="http://www.counterpane.com/">author's company's web site</a>.</p> +<hr> +<a name="secrets">Bruce Schneier</a><cite> Secrets and Lies</cite><br> +Wiley 2000, ISBN 0-471-25311-1 + +<p>An interesting discussion of security and privacy issues, written with +more of an "executive overview" approach rather than a narrow focus on the +technical issues. <strong>Highly recommended</strong>.</p> + +<p>This is worth reading even if you already understand security issues, or +think you do. To go deeper, follow it with Anderson's <a +href="#anderson">Security Engineering</a>.</p> +<hr> +<a name="VPNbook">Scott, Wolfe and Irwin <cite>Virtual Private +Networks</cite></a><br> +2nd edition, O'Reilly 1999 ISBN: 1-56592-529-7 + +<p>This is the only O'Reilly book, out of a dozen I own, that I'm +disappointed with. It deals mainly with building VPNs with various +proprietary tools -- <a href="glossary.html#PPTP">PPTP</a>, <a +href="glossary.html#SSH">SSH</a>, Cisco PIX, ... -- and touches only lightly +on IPsec-based approaches.</p> + +<p>That said, it appears to deal competently with what it does cover and it +has readable explanations of many basic VPN and security concepts. It may be +exactly what some readers require, even if I find the emphasis +unfortunate.</p> +<hr> +<a name="LASG">Kurt Seifried <cite>Linux Administrator's Security +Guide</cite></a> + +<p>Available online from <a +href="http://www.securityportal.com/lasg/">Security Portal</a>. It has fairly +extensive coverage of IPsec.</p> +<hr> +<a name="Smith">Richard E Smith <cite>Internet Cryptography</cite><br> +</a>ISBN 0-201-92480-3, Addison Wesley, 1997 + +<p>See the book's <a +href="http://www.visi.com/crypto/inet-crypto/index.html">home page</a></p> +<hr> +<a name="neal">Neal Stephenson <cite>Cryptonomicon</cite></a><br> +Hardcover ISBN -380-97346-4, Avon, 1999. + +<p>A novel in which cryptography and the net figure prominently. +<strong>Highly recommended</strong>: I liked it enough I immediately went out +and bought all the author's other books.</p> + +<p>There is also a paperback edition. Sequels are expected.</p> +<hr> +<a name="stevens">Stevens and Wright</a> <cite>TCP/IP Illustrated</cite><br> +Addison-Wesley +<ul> + <li>Vol. I: The Protocols 1994 ISBN:0-201-63346-9</li> + <li>Vol. II: The Implementation 1995 ISBN:0-201-63354-X</li> + <li>Vol. III: TCP for Transactions, HTTP, NNTP, and the UNIX Domain + Protocols 1996 ISBN: 0-201-63495-3</li> +</ul> + +<p>If you need to deal with the details of the network protocols, read either +this series or the <a href="#comer">Comer</a> series before you start reading +the RFCs.</p> +<hr> +<a name="Rubini">Rubini</a> <cite>Linux Device Drivers</cite><br> +O'Reilly & Associates, Inc. 1998 ISBN 1-56592-292-1 +<hr> +<a name="Zeigler">Robert Zeigler</a> <cite>Linux Firewalls</cite><br> +Newriders Publishing, 2000 ISBN 0-7537-0900-9 + +<p>A good book, with detailed coverage of ipchains(8) firewalls and of many +related issues.</p> +</body> +</html> diff --git a/doc/src/buildtools.html b/doc/src/buildtools.html new file mode 100644 index 000000000..c8cfa1fc8 --- /dev/null +++ b/doc/src/buildtools.html @@ -0,0 +1,27 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Tools used to build FreeSWAN releases (08-Mar-2002)</TITLE> + <!-- Created by: Michael Richardson, 08-Mar-2002 --> + + + </HEAD> + <BODY> + <H1>Tools used to build FreeSWAN releases</H1> + +<H2>man2html</H2> + +<P> +If you are not running RedHat, you will need man2html. This is part of the +"man" RPM on RedHat, whose sources can be found at <A HREF="ftp://ftp.win.tue.nl/pub/linux-local/utils/man/">ftp://ftp.win.tue.nl/pub/linux-local/utils/man/</A>. +</P> + +<P> +Note that the Debian package <A HREF="http://packages.debian.org/man2html">man2html</A> +and the one listed on Freshmeat at +<A HREF="http://freshmeat.net/projects/man2html/">man2html</A> will +not work. +</P> + + </BODY> +</HTML>
\ No newline at end of file diff --git a/doc/src/compat.html b/doc/src/compat.html new file mode 100644 index 000000000..a8e1455bf --- /dev/null +++ b/doc/src/compat.html @@ -0,0 +1,795 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN compatibility guide</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, compatibility"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: compat.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="compat">Linux FreeS/WAN Compatibility Guide</a></h1> + +<p>Much of this document is quoted directly from the Linux FreeS/WAN <a +href="mail.html">mailing list</a>. Thanks very much to the community of +testers, patchers and commenters there, especially the ones quoted below but +also various contributors we haven't quoted.</p> + +<h2><a name="spec">Implemented parts of the IPsec Specification</a></h2> + +<p>In general, do not expect Linux FreeS/WAN to do everything yet. This is a +work-in-progress and some parts of the IPsec specification are not yet +implemented.</p> + +<h3><a name="in">In Linux FreeS/WAN</a></h3> + +<p>Things we do, as of version 1.96:</p> +<ul> + <li>key management methods + <dl> + <dt>manually keyed</dt> + <dd>using keys stored in /etc/ipsec.conf</dd> + <dt>automatically keyed</dt> + <dd>Automatically negotiating session keys as required. All + connections are automatically re-keyed periodically. The <a + href="glossary.html#Pluto">Pluto</a> daemon implements this using + the <a href="glossary.html#IKE">IKE</a> protocol.</dd> + </dl> + </li> + <li>Methods of authenticating gateways for IKE + <dl> + <dt>shared secrets</dt> + <dd>stored in <a + href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a></dd> + <dt><a href="glossary.html#RSA">RSA</a> signatures</dt> + <dd>For details, see <a + href="manpage.d/ipsec_pluto.8.html">pluto(8)</a>.</dd> + <dt>looking up RSA authentication keys from <a + href="glossary.html#DNS">DNS</a>.</dt> + <dd>Note that this technique cannot be fully secure until <a + href="glossary.html#SDNS">secure DNS</a> is widely deployed.</dd> + </dl> + </li> + <li>groups for <a href="glossary.html#DH">Diffie-Hellman</a> key negotiation + <dl> + <dt>group 2, modp 1024-bit</dt> + <dt>group 5, modp 1536-bit</dt> + <dd>We implement these two groups. + <p>In negotiating a keying connection (ISAKMP SA, Phase 1) we + propose both groups when we are the initiator, and accept either + when a peer proposes them. Once the keying connection is made, we + propose only the alternative agreed there for data connections + (IPsec SA's, Phase 2) negotiated over that keying connection.</p> + </dd> + </dl> + </li> + <li>encryption transforms + <dl> + <dt><a href="glossary.html#DES">DES</a></dt> + <dd>DES is in the source code since it is needed to implement 3DES, + but single DES is not made available to users because <a + href="politics.html#desnotsecure">DES is insecure</a>.</dd> + <dt><a href="glossary.html#3DES">Triple DES</a></dt> + <dd>implemented, and used as the default encryption in Linux + FreeS/WAN.</dd> + </dl> + </li> + <li>authentication transforms + <dl> + <dt><a href="glossary.html#HMAC">HMAC</a> using <a + href="glossary.html#MD5">MD5</a></dt> + <dd>implemented, may be used in IKE or by by AH or ESP + transforms.</dd> + <dt><a href="glossary.html#HMAC">HMAC</a> using <a + href="glossary.html#SHA">SHA</a></dt> + <dd>implemented, may be used in IKE or by AH or ESP transforms.</dd> + </dl> + <p>In negotiations, we propose both of these and accept either.</p> + </li> + <li>compression transforms + <dl> + <dt>IPComp</dt> + <dd>IPComp as described in RFC 2393 was added for FreeS/WAN 1.6. Note + that Pluto becomes confused if you ask it to do IPComp when the + kernel cannot.</dd> + </dl> + </li> +</ul> + +<p>All combinations of implemented transforms are supported. Note that some +form of packet-level <strong>authentication is required whenever encryption +is used</strong>. Without it, the encryption will not be secure.</p> + +<h3><a name="dropped">Deliberately omitted</a></h3> +We do not implement everything in the RFCs because some of those things are +insecure. See our discussions of avoiding <a href="politics.html#weak">bogus +security</a>. + +<p>Things we deliberately omit which are required in the RFCs are:</p> +<ul> + <li>null encryption (to use ESP as an authentication-only service)</li> + <li>single DES</li> + <li>DH group 1, a 768-bit modp group</li> +</ul> + +<p>Since these are the only encryption algorithms and DH group the RFCs +require, it is possible in theory to have a standards-conforming +implementation which will not interpoperate with FreeS/WAN. Such an +implementation would be inherently insecure, so we do not consider this a +problem.</p> + +<p>Anyway, most implementations sensibly include more secure options as well, +so dropping null encryption, single DES and Group 1 does not greatly hinder +interoperation in practice.</p> + +<p>We also do not implement some optional features allowed by the RFCs:</p> +<ul> + <li>aggressive mode for negotiation of the keying channel or ISAKMP SA. + This mode is a little faster than main mode, but exposes more information + to an eavesdropper.</li> +</ul> + +<p>In theory, this should cause no interoperation problems since all +implementations are required to support the more secure main mode, whether or +not they also allow aggressive mode.</p> + +<p>In practice, it does sometimes produce problems with implementations such +as Windows 2000 where aggressive mode is the default. Typically, these are +easily solved with a configuration change that overrides that default.</p> + +<h3><a name="not">Not (yet) in Linux FreeS/WAN</a></h3> + +<p>Things we don't yet do, as of version 1.96:</p> +<ul> + <li>key management methods + <ul> + <li>authenticate key negotiations via local <a + href="glossary.html#PKI">PKI</a> server, but see links to user <a + href="web.html#patch">patches</a></li> + <li>authenticate key negotiations via <a + href="glossary.html#SDNS">secure DNS</a></li> + <li>unauthenticated key management, using <a + href="glossary.html#DH">Diffie-Hellman</a> key agreement protocol + without authentication. Arguably, this would be worth doing since it + is secure against all passive attacks. On the other hand, it is + vulnerable to an active <a + href="glossary.html#middle">man-in-the-middle attack</a>.</li> + </ul> + </li> + <li>encryption transforms + <p>Currently <a href="glossary.html#3DES">Triple DES</a> is the only + encryption method Pluto will negotiate.</p> + <p>No additional encryption transforms are implemented, though the RFCs + allow them and some other IPsec implementations support various of them. + We are not eager to add more. See this <a + href="faq.html#other.cipher">FAQ question</a>.</p> + <p><a href="glossary.html#AES">AES</a>, the successor to the DES + standard, is an excellent candidate for inclusion in FreeS/WAN, see links + to user <a href="web.html#patch">patches</a>.</p> + </li> + <li>authentication transforms + <p>No optional additional authentication transforms are currently + implemented. Likely <a href="glossary.html#SHA-256">SHA-256, SHA-384 and + SHA-512</a> will be added when AES is.</p> + </li> + <li>Policy checking on decrypted packets + <p>To fully comply with the RFCs, it is not enough just to accept only + packets which survive any firewall rules in place to limit what IPsec + packets get in, and then pass KLIPS authentication. That is what + FreeS/WAN currently does.</p> + <p>We should also apply additional tests, for example ensuring that all + packets emerging from a particular tunnel have source and destination + addresses that fall within the subnets defined for that tunnel, and that + packets with those addresses that did not emerge from the appropriate + tunnel are disallowed.</p> + <p>This will be done as part of a KLIPS rewrite. See these <a + href="intro.html#applied">links</a> and the <a href="mail.html">design + mailing list</a> for discussion.</p> + </li> +</ul> + +<h2><a name="pfkey">Our PF-Key implementation</a></h2> + +<p>We use PF-key Version Two for communication between the KLIPS kernel code +and the Pluto Daemon. PF-Key v2 is defined by <a +href="http://www.normos.org/ietf/rfc/rfc2367.txt">RFC 2367</a>.</p> + +<p>The "PF" stands for Protocol Family. PF-Inet defines a kernel/userspace +interface for the TCP/IP Internet protocols (TCP/IP), and other members of +the PF series handle Netware, Appletalk, etc. PF-Key is just a PF for +key-related matters.</p> + +<h3><a name="pfk.port">PF-Key portability</a></h3> + +<p>PF-Key came out of Berkeley Unix work and is used in the various BSD IPsec +implementations, and in Solaris. This means there is some hope of porting our +Pluto(8) to one of the BSD distributions, or of running their photurisd(8) on +Linux if you prefer <a href="glossary.html#photuris">Photuris</a> key +management over IKE.</p> + +<p>It is, however, more complex than that. The PK-Key RFC deliberately deals +only with keying, not policy management. The three PF-Key implementations we +have looked at -- ours, OpenBSD and KAME -- all have extensions to deal with +security policy, and the extensions are different. There have been +discussions aimed at sorting out the differences, perhaps for a version three +PF-Key spec. All players are in favour of this, but everyone involved is busy +and it is not clear whether or when these discussions might bear fruit.</p> + +<h2><a name="otherk">Kernels other than the latest 2.2.x and 2.4.y</a></h2> + +<p>We develop and test on Redhat Linux using the most recent kernel in the +2.2 and 2.4 series. In general, we recommend you use the latest kernel in one +of those series. Complications and caveats are discussed below.</p> + +<h3><a name="kernel.2.0">2.0.x kernels</a></h3> + +<p>Consider upgrading to the 2.2 kernel series. If you want to stay with the +2.0 series, then we strongly recommend 2.0.39. Some useful security patches +were added in 2.0.38.</p> + +<p>Various versions of the code have run at various times on most 2.0.xx +kernels, but the current version is only lightly tested on 2.0.39, and not at +all on older kernels.</p> + +<p>Some of our patches for older kernels are shipped in 2.0.37 and later, so +they are no longer provided in FreeS/WAN. This means recent versions of +FreeS/WAN will probably not compile on anything earlier than 2.0.37.</p> + +<h3><a name="kernel.production">2.2 and 2.4 kernels</a></h3> +<dl> + <dt>FreeS/WAN 1.0</dt> + <dd>ran only on 2.0 kernels</dd> + <dt>FreeS/WAN 1.1 to 1.8</dt> + <dd>ran on 2.0 or 2.2 kernels<br> + ran on some development kernels, 2.3 or 2.4-test</dd> + <dt>FreeS/WAN 1.9 to 1.96</dt> + <dd>runs on 2.0, 2.2 or 2.4 kernels</dd> +</dl> + +<p>In general, <strong>we suggest the latest 2.2 kernel or 2.4 for production +use</strong>.</p> + +<p>Of course no release can be guaranteed to run on kernels more recent than +it is, so quite often there will be no stable FreeS/WAN for the absolute +latest kernel. See the <a href="faq.html#k.versions">FAQ</a> for +discussion.</p> + +<h2><a name="otherdist">Intel Linux distributions other than Redhat</a></h2> + +<p>We develop and test on Redhat 6.1 for 2.2 kernels, and on Redhat 7.1 or +7.2 for 2.4, so minor changes may be required for other distributions.</p> + +<h3><a name="rh7">Redhat 7.0</a></h3> + +<p>There are some problems with FreeS/WAN on Redhat 7.0. They are soluble, +but we recommend you upgrade to a later Redhat instead..</p> + +<p>Redhat 7 ships with two compilers.</p> +<ul> + <li>Their <var>gcc</var> is version 2.96. Various people, including the GNU + compiler developers and Linus, have said fairly emphatically that using + this was a mistake. 2.96 is a development version, not intended for + production use. In particular, it will not compile a Linux kernel.</li> + <li>Redhat therefore also ship a separate compiler, which they call + <var>kgcc</var>, for compiling kernels.</li> +</ul> + +<p>Kernel Makefiles have <var>gcc</var> as a default, and must be adjusted to +use <var>kgcc</var> before a kernel will compile on 7.0. This mailing list +message gives details:</p> +<pre>Subject: Re: AW: Installing IPsec on Redhat 7.0 + Date: Thu, 1 Feb 2001 14:32:52 -0200 (BRST) + From: Mads Rasmussen <mads@cit.com.br> + +> From www.redhat.com/support/docs/gotchas/7.0/gotchas-7-6.html#ss6.1 + +cd to /usr/src/linux and open the Makefile in your favorite editor. You +will need to look for a line similar to this: + +CC = $(CROSS_COMPILE)gcc -D__KERNEL__ -I$(HPATH) + +This line specifies which C compiler to use to build the kernel. It should +be changed to: + +CC = $(CROSS_COMPILE)kgcc -D__KERNEL__ -I$(HPATH) + +for Red Hat Linux 7. The kgcc compiler is egcs 2.91.66. From here you can +proceed with the typical compiling steps.</pre> + +<p>Check the <a href="mail.html">mailing list</a> archive for more recent +news.</p> + +<h3><a name="suse">SuSE Linux</a></h3> + +<p>SuSE 6.3 and later versions, at least in Europe, ship with FreeS/WAN +included.</p> + +<P>FreeS/WAN packages distributed for SuSE 7.0-7.2 were somehow +miscompiled. You can find fixed packages on +<A HREF="http://www.suse.de/~garloff/linux/FreeSWAN"> +Kurt Garloff's page</A>.</P> + +<p>Here are some notes for an earlier SuSE version.</p> + +<h4>SuSE Linux 5.3</h4> +<pre>Date: Mon, 30 Nov 1998 +From: Peter Onion <ponion@srd.bt.co.uk> + +... I got Saturdays snapshot working between my two SUSE5.3 machines at home. + +The mods to the install process are quite simple. From memory and looking at +the files on the SUSE53 machine here at work.... + +And extra link in each of the /etc/init.d/rc?.d directories called K35ipsec +which SUSE use to shut a service down. + +A few mods in /etc/init.d/ipsec to cope with the different places that SUSE +put config info, and remove the inculsion of /etc/rc.d/init.d/functions and . +/etc/sysconfig/network as they don't exists and 1st one isn't needed anyway. + +insert ". /etc/rc.config" to pick up the SUSE config info and use + + if test -n "$NETCONFIG" -a "$NETCONFIG" != "YAST_ASK" ; then + +to replace + + [ ${NETWORKING} = "no" ] && exit 0 + +Create /etc/sysconfig as SUSE doesn't have one. + +I think that was all (but I prob forgot something)....</pre> + +<p>You may also need to fiddle initialisation scripts to ensure that +<var>/var/run/pluto.pid</var> is removed when rebooting. If this file is +present, Pluto does not come up correctly.</p> + +<h3><a name="slack">Slackware</a></h3> +<pre>Subject: Re: linux-IPsec: Slackware distribution + Date: Thu, 15 Apr 1999 12:07:01 -0700 + From: Evan Brewer <dmessiah@silcon.com> + +> Very shortly, I will be needing to install IPsec on at least gateways that +> are running Slackware. . . . + +The only trick to getting it up is that on the slackware dist there is no +init.d directory in /etc/rc.d .. so create one. Then, what I do is take the +IPsec startup script which normally gets put into the init.d directory, and +put it in /etc/rc.d and name ir rc.ipsec .. then I symlink it to the file +in init.d. The only file in the dist you need to really edit is the +utils/Makefile, setup4: + +Everything else should be just fine.</pre> + +<p>A year or so later:</p> +<pre>Subject: Re: HTML Docs- Need some cleanup? + Date: Mon, 8 Jan 2001 + From: Jody McIntyre <jodym@oeone.com> + +I have successfully installed FreeS/WAN on several Slackware 7.1 machines. +FreeS/WAN installed its rc.ipsec file in /etc/rc.d. I had to manually call +this script from rc.inet2. This seems to be an easier method than Evan +Brewer's.</pre> + +<h3><a name="deb">Debian</a></h3> + +<p>A recent (Nov 2001) mailing list points to a <a +href="http://www.thing.dyndns.org/debian/vpn.htm">web page</a> on setting up +several types of tunnel, including IPsec, on Debian.</p> + +<p>Some older information:</p> +<pre>Subject: FreeS/WAN 1.0 on Debian 2.1 + Date: Tue, 20 Apr 1999 + From: Tim Miller <cerebus+counterpane@haybaler.sackheads.org> + + Compiled and installed without error on a Debian 2.1 system +with kernel-source-2.0.36 after pointing RCDIR in utils/Makefile to +/etc/init.d. + + /var/lock/subsys/ doesn't exist on Debian boxen, needs to be +created; not a fatal error. + + Finally, IPsec scripts appear to be dependant on GNU awk +(gawk); the default Debian awk (mawk-1.3.3-2) had fatal difficulties. +With gawk installed and /etc/alternatives/awk linked to /usr/bin/gawk +operation appears flawless.</pre> + +<p>The scripts in question have been modified since this was posted. Awk +versions should no longer be a problem.</p> + +<h3><a name="caldera">Caldera</a></h3> +<pre>Subject: Re: HTML Docs- Need some cleanup? + Date: Mon, 08 Jan 2001 + From: Andy Bradford <andyb@calderasystems.com> + +On Sun, 07 Jan 2001 22:59:05 EST, Sandy Harris wrote: + +> Intel Linux distributions other than Redhat 5.x and 6.x +> Redhat 7.0 +> SuSE Linux +> SuSE Linux 5.3 +> Slackware +> Debian + +Can you please include Caldera in this list? I have tested it since +FreeS/Wan 1.1 and it works great with our systems---provided one +follows the FreeS/Wan documentation. :-) + +Thank you, +Andy</pre> + +<h2><a name="CPUs">CPUs other than Intel</a></h2> + +<p>FreeS/WAN has been run sucessfully on a number of different CPU +architectures. If you have tried it on one not listed here, please post to +the <a href="mail.html">mailing list</a>.</p> + +<h3><a name=" strongarm">Corel Netwinder (StrongARM CPU)</a></h3> +<pre>Subject: linux-ipsec: Netwinder diffs +Date: Wed, 06 Jan 1999 +From: rhatfield@plaintree.com + +I had a mistake in my IPsec-auto, so I got things working this morning. + +Following are the diffs for my changes. Probably not the best and cleanest way +of doing it, but it works. . . . </pre> + +<p>These diffs are in the 0.92 and later distributions, so these should work +out-of-the-box on Netwinder.</p> + +<h3><a name="yellowdog">Yellow Dog Linux on Power PC</a></h3> +<pre>Subject: Compiling FreeS/WAN 1.1 on YellowDog Linux (PPC) + Date: 11 Dec 1999 + From: Darron Froese <darron@fudgehead.com> + +I'm summarizing here for the record - because it's taken me many hours to do +this (multiple times) and because I want to see IPsec on more linuxes than +just x86. + +Also, I can't remember if I actually did summarize it before... ;-) I'm +working too many late hours. + +That said - here goes. + +1. Get your linux kernel and unpack into /usr/src/linux/ - I used 2.2.13. +<http://www.kernel.org/pub/linux/kernel/v2.2/linux-2.2.13.tar.bz2> + +2. Get FreeS/WAN and unpack into /usr/src/freeswan-1.1 +<ftp://ftp.xs4all.nl/pub/crypto/freeswan/freeswan-1.1.tar.gz> + +3. Get the gmp src rpm from here: +<ftp://ftp.yellowdoglinux.com//pub/yellowdog/champion-1.1/SRPMS/SRPMS/gmp-2.0.2-9a.src.rpm> + +4. Su to root and do this: rpm --rebuild gmp-2.0.2-9a.src.rpm + +You will see a lot of text fly by and when you start to see the rpm +recompiling like this: + +Executing: %build ++ umask 022 ++ cd /usr/src/redhat/BUILD ++ cd gmp-2.0.2 ++ libtoolize --copy --force +Remember to add `AM_PROG_LIBTOOL' to `configure.in'. +You should add the contents of `/usr/share/aclocal/libtool.m4' to +`aclocal.m4'. ++ CFLAGS=-O2 -fsigned-char ++ ./configure --prefix=/usr + +Hit Control-C to stop the rebuild. NOTE: We're doing this because for some +reason the gmp source provided with FreeS/WAN 1.1 won't build properly on +ydl. + +cd /usr/src/redhat/BUILD/ +cp -ar gmp-2.0.2 /usr/src/freeswan-1.1/ +cd /usr/src/freeswan-1.1/ +rm -rf gmp +mv gmp-2.0.2 gmp + +5. Open the freeswan Makefile and change the line that says: +KERNEL=$(b)zimage (or something like that) to +KERNEL=vmlinux + +6. cd ../linux/ + +7. make menuconfig +Select an option or two and then exit - saving your changes. + +8. cd ../freeswan-1.1/ ; make menugo + +That will start the whole process going - once that's finished compiling, +you have to install your new kernel and reboot. + +That should build FreeS/WAN on ydl (I tried it on 1.1).</pre> +And a later message on the same topic: +<pre>Subject: Re: FreeS/WAN, PGPnet and E-mail + Date: Sat, 22 Jan 2000 + From: Darron Froese <darron@fudgehead.com> + +on 1/22/00 6:47 PM, Philip Trauring at philip@trauring.com wrote: + +> I have a PowerMac G3 ... + +The PowerMac G3 can run YDL 1.1 just fine. It should also be able to run +FreeS/WAN 1.2patch1 with a couple minor modifications: + +1. In the Makefile it specifies a bzimage for the kernel compile - you have +to change that to vmlinux for the PPC. + +2. The gmp source that comes with FreeS/WAN (for whatever reason) fails to +compile. I have gotten around this by getting the gmp src rpm from here: + +ftp://ftp.yellowdoglinux.com//pub/yellowdog/champion-1.1/SRPMS/SRPMS/gmp-2.0.2-9a.src.rpm + +If you rip the source out of there - and place it where the gmp source +resides it will compile just fine.</pre> + +<p>FreeS/WAN no longer includes GMP source.</p> + +<h3><a name="mklinux">Mklinux</a></h3> + +<p>One user reports success on the Mach-based +<strong>m</strong>icro<strong>k</strong>ernel Linux.</p> +<pre>Subject: Smiles on sparc and ppc + Date: Fri, 10 Mar 2000 + From: Jake Hill <jah@alien.bt.co.uk> + +You may or may not be interested to know that I have successfully built +FreeS/WAN on a number of non intel alpha architectures; namely on ppc +and sparc and also on osfmach3/ppc (MkLinux). I can report that it just +works, mostly, with few changes.</pre> + +<h3><a name="alpha">Alpha 64-bit processors</a></h3> +<pre>Subject: IT WORKS (again) between intel & alpha :-))))) + Date: Fri, 29 Jan 1999 + From: Peter Onion <ponion@srd.bt.co.uk> + +Well I'm happy to report that I've got an IPsec connection between by intel & alpha machines again :-)) + +If you look back on this list to 7th of December I wrote... + +-On 07-Dec-98 Peter Onion wrote: +-> +-> I've about had enuf of wandering around inside the kernel trying to find out +-> just what is corrupting outgoing packets... +- +-Its 7:30 in the evening ..... +- +-I FIXED IT :-)))))))))))))))))))))))))))))))) +- +-It was my own fault :-(((((((((((((((((( +- +-If you ask me very nicly I'll tell you where I was a little too over keen to +-change unsigned long int __u32 :-) OPSE ... +- +-So tomorrow it will full steam ahead to produce a set of diffs/patches against +-0.91 +- +-Peter Onion.</pre> + +<p>In general (there have been some glitches), FreeS/WAN has been running on +Alphas since then.</p> + +<h3><a name="SPARC">Sun SPARC processors</a></h3> + +<p>Several users have reported success with FreeS/WAN on SPARC Linux. Here is +one mailing list message:</p> +<pre>Subject: Smiles on sparc and ppc + Date: Fri, 10 Mar 2000 + From: Jake Hill <jah@alien.bt.co.uk> + +You may or may not be interested to know that I have successfully built +FreeS/WAN on a number of non intel alpha architectures; namely on ppc +and sparc and also on osfmach3/ppc (MkLinux). I can report that it just +works, mostly, with few changes. + +I have a question, before I make up some patches. I need to hack +gmp/mpn/powerpc32/*.s to build them. Is this ok? The changes are +trivial, but could I also use a different version of gmp? Is it vanilla +here? + +I guess my only real headache is from ipchains, which appears to stop +running when IPsec has been started for a while. This is with 2.2.14 on +sparc.</pre> + +<p>This message, from a different mailing list, may be relevant for anyone +working with FreeS/WAN on Suns:</p> +<pre>Subject: UltraSPARC DES assembler + Date: Thu, 13 Apr 2000 + From: svolaf@inet.uni2.dk (Svend Olaf Mikkelsen) + To: coderpunks@toad.com + +An UltraSPARC assembler version of the LibDES/SSLeay/OpenSSL des_enc.c +file is available at http://inet.uni2.dk/~svolaf/des.htm. + +This brings DES on UltraSPARC from slower than Pentium at the same +clock speed to significantly faster.</pre> + +<h3><a name="mips">MIPS processors</a></h3> + +<p>We know FreeS/WAN runs on at least some MIPS processors because <a +href="http://www.lasat.com">Lasat</a> manufacture an IPsec box based on an +embedded MIPS running Linux with FreeS/WAN. We have no details.</p> + +<h3><a name="crusoe">Transmeta Crusoe</a></h3> + +<p>The Merilus <a +href="http://www.merilus.com/products/fc/index.shtml">Firecard</a>, a Linux +firewall on a PCI card, is based on a Crusoe processor and supports +FreeS/WAN.</p> + +<h3><a name="coldfire">Motorola Coldfire</a></h3> +<pre>Subject: Re: Crypto hardware support + Date: Mon, 03 Jul 2000 + From: Dan DeVault <devault@tampabay.rr.com> + +.... I have been running +uClinux with FreeS/WAN 1.4 on a system built by Moreton Bay ( +http://www.moretonbay.com ) and it was using a Coldfire processor +and was able to do the Triple DES encryption at just about +1 mbit / sec rate....... they put a Hi/Fn 7901 hardware encryption +chip on their board and now their system does over 25 mbit of 3DES +encryption........ pretty significant increase if you ask me.</pre> + +<h2><a name="multiprocessor">Multiprocessor machines</a></h2> + +<p>FreeS/WAN is designed to work on SMP (symmetric multi-processing) Linux +machines and is regularly tested on dual processor x86 machines.</p> + +<p>We do not know of any testing on multi-processor machines with other CPU +architectures or with more than two CPUs. Anyone who does test this, please +report results to the <a href="mail.html">mailing list</a>.</p> + +<p>The current design does not make particularly efficient use of +multiprocessor machines; some of the kernel work is single-threaded.</p> + +<h2><a name="hardware">Support for crypto hardware</a></h2> + +<p>Supporting hardware cryptography accelerators has not been a high priority +for the development team because it raises a number of fairly complex +issues:</p> +<ul> + <li>Can you trust the hardware? If it is not Open Source, how do you audit + its security? Even if it is, how do you check that the design has no + concealed traps?</li> + <li>If an interface is added for such hardware, can that interface be + subverted or misused?</li> + <li>Is hardware acceleration actually a performance win? It clearly is in + many cases, but on a fast machine it might be better to use the CPU for + the encryption than to pay the overheads of moving data to and from a + crypto board.</li> + <li>the current KLIPS code does not provide a clean interface for hardware + accelerators</li> +</ul> + +<p>That said, we have a <a href="#coldfire">report</a> of FreeS/WAN working +with one crypto accelerator and some work is going on to modify KLIPS to +create a clean generic interface to such products. See this <a +href="http://www.jukie.net/~bart/linux-ipsec/">web page</a> for some of the +design discussion.</p> + +<p>More recently, a patch to support some hardware accelerators has been +posted:</p> +<pre>Subject: [Design] [PATCH] H/W acceleration patch + Date: Tue, 18 Sep 2001 + From: "Martin Gadbois" <martin.gadbois@colubris.com> + +Finally!! +Here's a web site with H/W acceleration patch for FreeS/WAN 1.91, including +S/W and Hifn 7901 crypto support. + +http://sources.colubris.com/ + +Martin Gadbois</pre> + +<p>Hardware accelerators could take performance well beyond what FreeS/WAN +can do in software (discussed <a href="performance.html">here</a>). Here is +some discussion off the IETF IPsec list, October 2001:</p> +<pre> ... Currently shipping chips deliver, 600 mbps throughput on a single + stream of 3DES IPsec traffic. There are also chips that use multiple + cores to do 2.4 gbps. We (Cavium) and others have announced even faster + chips. ... Mid 2002 versions will handle at line rate (OC48 and OC192) + IPsec and SSL/TLS traffic not only 3DES CBC but also AES and arc4.</pre> + +<p>The patches to date support chips that have been in production for some +time, not the state-of-the-art latest-and-greatest devices described in that +post. However, they may still outperform software and they almost certainly +reduce CPU overhead.</p> + +<h2><a name="ipv6">IP version 6 (IPng)</a></h2> + +<p>The Internet currently runs on version four of the IP protocols. IPv4 is +what is in the standard Linux IP stack, and what FreeS/WAN was built for. In +IPv4, IPsec is an optional feature.</p> + +<p>The next version of the IP protocol suite is version six, usually +abbreviated either as "IPv6" or as "IPng" for "IP: the next generation". For +IPv6, IPsec is a required feature. Any machine doing IPv6 is required to +support IPsec, much as any machine doing (any version of) IP is required to +support ICMP.</p> + +<p>There is a Linux implementation of IPv6 in Linux kernels 2.2 and above. +For details, see the <a +href="http://www.cs-ipv6.lancs.ac.uk/ipv6/systems/linux/faq/">FAQ</a>. It +does not yet support IPsec. The <a +href="http://www.linux-ipv6.org/">USAGI</a> project are also working on IPv6 +for Linux.</p> + +<p>FreeS/WAN was originally built for the current standard, IPv4, but we are +interested in seeing it work with IPv6. Some progress has been made, and a +patched version with IPv6 support is <a +href="http://www.ipv6.iabg.de/downloadframe/index.html">available</a>. For +more recent information, check the <a href="mail.html">mailing list</a>.</p> + +<h3><a name="v6.back">IPv6 background</a></h3> + +<p>IPv6 has been specified by an IETF <a +href="http://www.ietf.org/html.charters/ipngwg-charter.html">working +group</a>. The group's page lists over 30 RFCs to date, and many Internet +Drafts as well. The overview is <a +href="http://www.ietf.org/rfc/rfc2460.txt">RFC 2460</a>. Major features +include:</p> +<ul> + <li>expansion of the address space from 32 to 128 bits,</li> + <li>changes to improve support for + <ul> + <li>mobile IP</li> + <li>automatic network configuration</li> + <li>quality of service routing</li> + <li>...</li> + </ul> + </li> + <li>improved security via IPsec</li> +</ul> + +<p>A number of projects are working on IPv6 implementation. A prominent Open +Source effort is <a href="http://www.kame.net/">KAME</a>, a collaboration +among several large Japanese companies to implement IPv6 for Berkeley Unix. +Other major players are also working on IPv6. For example, see pages at:</p> +<ul> + <li><a + href="http://playground.sun.com/pub/ipng/html/ipng-main.html">Sun</a></li> + <li><a + href="http://www.cisco.com/warp/public/732/ipv6/index.html">Cisco</a></li> + <li><a + href="http://www.microsoft.com/windows2000/techinfo/howitworks/communications/networkbasics/IPv6.asp">Microsoft</a></li> +</ul> + +<p>The <a href="http://www.6bone.net/">6bone</a> (IPv6 backbone) testbed +network has been up for some time. There is an active <a +href="http://www.ipv6.org/">IPv6 user group</a>.</p> + +<p>One of the design goals for IPv6 was that it must be possible to convert +from v4 to v6 via a gradual transition process. Imagine the mess if there +were a "flag day" after which the entire Internet used v6, and all software +designed for v4 stopped working. Almost every computer on the planet would +need major software changes! There would be huge costs to replace older +equipment. Implementers would be worked to death before "the day", systems +administrators and technical support would be completely swamped after it. +The bugs in every implementation would all bite simultaneously. Large chunks +of the net would almost certainly be down for substantial time periods. +...</p> + +<p>Fortunately, the design avoids any "flag day". It is therefore a little +tricky to tell how quickly IPv6 will take over. The transition has certainly +begun. For examples, see announcements from <a +href="http://www.mailbase.ac.uk/lists/internet2/2000-03/0016.html">NTT</a> +and <a href="http://www.vnunet.com/News/1102383">Nokia</a>. However, it is +not yet clear how quickly the process will gain momentum, or when it will be +completed. Likely large parts of the Internet will remain with IPv4 for years +to come.</p> +</body> +</html> diff --git a/doc/src/config.html b/doc/src/config.html new file mode 100644 index 000000000..b98e452db --- /dev/null +++ b/doc/src/config.html @@ -0,0 +1,394 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN configuration</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, installation, quickstart"> + <!-- + + Written by Claudia Schmeing for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: config.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> +<BODY> +<H1><A NAME="config">How to configure FreeS/WAN</A></H1> + +<P>This page will teach you how to configure a simple network-to-network +link or a Road Warrior connection between two Linux FreeS/WAN boxes. +</P> + +<P>See also these related documents:</P> +<UL> +<LI>our <A HREF="quickstart.html#quickstart">quickstart</A> guide +to <A HREF="glossary.html#carpediem">opportunistic encryption</A></LI> +<LI>our guide to configuration with +<A HREF="policygroups.html#policygroups">policy groups</A></LI> +<LI>our +<A HREF="adv_config.html#adv_config">advanced configuration</A> +document</LI> +</UL> +<P> +The network-to-network setup allows you to connect two office +networks into one Virtual Private Network, while the Road Warrior +connection secures a laptop's telecommute to work. +Our examples also show the basic procedure on the Linux FreeS/WAN side where +another IPsec peer is in play.</P> + +<P> +Shortcut to <A HREF="#config.netnet">net-to-net</A>.<BR> +Shortcut to <A HREF="#config.rw">Road Warrior</A>. +</P> + +<H2>Requirements</H2> + +<P>To configure the network-to-network connection you must have:</P> +<UL> +<LI>two Linux gateways with static IPs</LI> +<LI>a network behind each gate. Networks must have non-overlapping IP ranges.</LI> +<LI>Linux FreeS/WAN <A HREF="install.html#install">installed</A> + on both gateways</LI> +<LI><A HREF="http://www.tcpdump.org"><VAR>tcpdump</VAR></A> on the local gate, + to test the connection</LI> +</UL> +<P>For the Road Warrior you need:</P> +<UL> +<LI>one Linux box with a static IP</LI> +<LI>a Linux laptop with a dynamic IP</LI> +<LI>Linux FreeS/WAN installed on both</LI> +<LI>for testing, <VAR>tcpdump</VAR> on your gateway or laptop</LI> +</UL> + +<P>If both IPs are dynamic, your situation is a bit trickier. Your best bet +is a variation on the <A HREF="#config.rw">Road Warrior</A>, as described +in <A HREF="http://lists.freeswan.org/archives/users/2003-October/msg00282.html">this mailing list message</A>. + +<H2><A name="config.netnet"></A>Net-to-Net connection</H2> + + +<H3><A name="netnet.info.ex">Gather information</A></H3> + +<P>For each gateway, compile the following information:</P> +<UL> +<LI>gateway IP</LI> +<LI>IP range of the subnet you will be protecting. This doesn't have to + be your whole physical subnet.</LI> +<LI>a name by which that gateway can identify itself for IPsec +negotiations. Its form is a Fully Qualified Domain Name preceded by +an @ sign, ie. @xy.example.com. +<BR>It does not need to be within a domain that you own. It can be a made-up +name.</LI> +</UL> + + +<H4>Get your leftrsasigkey</H4> +<P>On your local Linux FreeS/WAN gateway, print your IPsec public key:</P> +<PRE> ipsec showhostkey --left</PRE> +<P>The output should look like this (with the key shortened for easy + reading):</P> +<PRE> # RSA 2048 bits xy.example.com Fri Apr 26 15:01:41 2002 + leftrsasigkey=0sAQOnwiBPt...</PRE> + +<P>Don't have a key? Use +<A HREF="manpage.d/ipsec_newhostkey.8.html"><VAR>ipsec newhostkey</VAR></A> +to create one. + +<H4>...and your rightrsasigkey</H4> +<P>Get a console on the remote side:</P> +<PRE> ssh2 ab.example.com</PRE> +<P>In that window, type:</P> +<PRE> ipsec showhostkey --right</PRE> +<P>You'll see something like:</P> +<PRE> # RSA 2192 bits ab.example.com Thu May 16 15:26:20 2002 + rightrsasigkey=0sAQOqH55O...</PRE> + +<H3>Edit <VAR>/etc/ipsec.conf</VAR></H3> + +<P>Back on the local gate, copy our template to <VAR>/etc/ipsec.conf</VAR>. +(on Mandrake, <VAR>/etc/freeswan/ipsec.conf</VAR>). +Substitute the information you've gathered for our example data.</P> +<PRE>conn net-to-net + left=192.0.2.2 # Local vitals + leftsubnet=192.0.2.128/29 # + leftid=@xy.example.com # + leftrsasigkey=0s1LgR7/oUM... # + leftnexthop=%defaultroute # correct in many situations + right=192.0.2.9 # Remote vitals + rightsubnet=10.0.0.0/24 # + rightid=@ab.example.com # + rightrsasigkey=0sAQOqH55O... # + rightnexthop=%defaultroute # correct in many situations + auto=add # authorizes but doesn't start this + # connection at startup</PRE> + +<P> +"Left" and "right" should represent the machines that have FreeS/WAN installed +on them, and "leftsubnet" and "rightsubnet" machines that are being protected. +/32 is assumed for left/right and left/rightsubnet parameters. +</P> + +<P>Copy <VAR>conn net-to-net</VAR> to the remote-side /etc/ipsec.conf. +If you've made no other modifications to either <VAR>ipsec.conf</VAR>, +simply:</P> +<PRE> scp2 ipsec.conf root@ab.example.com:/etc/ipsec.conf</PRE> + +<H3>Start your connection</H3> + +<P>Locally, type:</P> +<PRE> ipsec auto --up net-to-net</PRE> + +<P>You should see:</P> +<PRE> 104 "net-net" #223: STATE_MAIN_I1: initiate + 106 "net-net" #223: STATE_MAIN_I2: sent MI2, expecting MR2 + 108 "net-net" #223: STATE_MAIN_I3: sent MI3, expecting MR3 + 004 "net-net" #223: STATE_MAIN_I4: ISAKMP SA established + 112 "net-net" #224: STATE_QUICK_I1: initiate + 004 "net-net" #224: STATE_QUICK_I2: sent QI2, IPsec SA established</PRE> + +<P>The important thing is <VAR>IPsec SA established</VAR>. If you're +unsuccessful, see our +<A HREF="trouble.html#trouble">troubleshooting tips</A>.</P> + + +<H3>Do not MASQ or NAT packets to be tunneled</H3> + +<P>If you are using <A HREF="glossary.html#masq">IP masquerade</A> or +<A HREF="glossary.html#NAT.gloss">Network Address Translation (NAT)</A> +on either gateway, +you must now exempt the packets you wish to tunnel from this treatment. +For example, if you have a rule like:</P> + +<PRE>iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE +</PRE> + +<P>change it to something like:</P> +<PRE>iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -d \! 192.0.2.128/29 -j MASQUERADE</PRE> + +<P>This may be necessary on both gateways.</P> + + +<H3>Test your connection</H3> + +<P>Sit at one of your local subnet nodes (not the gateway), and ping a subnet +node on the other (again, not the gateway).</P> + +<PRE> ping fileserver.toledo.example.com</PRE> + +<P>While still pinging, go to the local gateway and snoop your outgoing +interface, for example:</P> +<PRE> tcpdump -i ppp0</PRE> +<P>You want to see ESP (Encapsulating Security Payload) packets moving +<B>back and forth</B> between the two gateways at the same frequency as +your pings:</P> +<PRE> 19:16:32.046220 192.0.2.2 > 192.0.2.9: ESP(spi=0x3be6c4dc,seq=0x3) + 19:16:32.085630 192.0.2.9 > 192.0.2.2: ESP(spi=0x5fdd1cf8,seq=0x6)</PRE> + +<P>If you see this, congratulations are in order! You have a tunnel which +will protect any IP data from one subnet +to the other, as it passes between the two gates. +If not, go and <A HREF="trouble.html#trouble">troubleshoot</A>.</P> + +<P>Note: your new tunnel protects only net-net traffic, not +gateway-gateway, or gateway-subnet. If you need this (for example, if +machines on one net need to securely contact a fileserver on the +IPsec gateway), you'll need to create +<A HREF="adv_config.html#adv_config">extra connections</A>.</P> + + +<H3>Finishing touches</H3> + +<P>Now that your connection works, name it something sensible, like:</P> +<PRE>conn winstonnet-toledonet</PRE> +<P>To have the tunnel come up on-boot, replace</P> +<PRE> auto=add</PRE> +<P>with:</P> +<PRE> auto=start</PRE> +<P>Copy these changes to the other side, for example:</P> +<PRE> scp2 ipsec.conf root@ab.example.com:/etc/ipsec.conf</PRE> +<P>Enjoy!</P> + + + +<H2><A name="config.rw"></A>Road Warrior Configuration</H2> + +<H3><A name="rw.info.ex">Gather information</A></H3> + +<P>You'll need to know:</P> +<UL> +<LI>the gateway's static IP</LI> +<LI>the IP range of the subnet behind that gateway</LI> +<LI>a name by which each side can identify itself for IPsec +negotiations. Its form is a Fully Qualified Domain Name preceded by +an @ sign, ie. @road.example.com. +<BR>It does not need to be within a domain that you own. It can be a made-up +name.</LI> +</UL> + +<H4>Get your leftrsasigkey...</H4> +<P>On your laptop, print your IPsec public key:</P> +<PRE> ipsec showhostkey --left</PRE> +<P>The output should look like this (with the key shortened for easy + reading):</P> +<PRE> # RSA 2192 bits road.example.com Sun Jun 9 02:45:02 2002 + leftrsasigkey=0sAQPIPN9uI...</PRE> + +<P>Don't have a key? See +<A HREF="old_config.html#genrsakey">these instructions</A>. + + +<H4>...and your rightrsasigkey</H4> +<P>Get a console on the gateway:</P> +<PRE> ssh2 xy.example.com</PRE> +<P>View the gateway's public key with:</P> +<PRE> ipsec showhostkey --right</PRE> +<P>This will yield something like</P> +<PRE> # RSA 2048 bits xy.example.com Fri Apr 26 15:01:41 2002 + rightrsasigkey=0sAQOnwiBPt...</PRE> + + +<H3>Customize <VAR>/etc/ipsec.conf</VAR></H3> + +<P>On your laptop, copy this template to <VAR>/etc/ipsec.conf</VAR>. +(on Mandrake, <VAR>/etc/freeswan/ipsec.conf</VAR>). +Substitute the information you've gathered for our example data.</P> +<PRE>conn road + left=%defaultroute # Picks up our dynamic IP + leftnexthop=%defaultroute # + leftid=@road.example.com # Local information + leftrsasigkey=0sAQPIPN9uI... # + right=192.0.2.10 # Remote information + rightsubnet=10.0.0.0/24 # + rightid=@xy.example.com # + rightrsasigkey=0sAQOnwiBPt... # + auto=add # authorizes but doesn't start this + # connection at startup</PRE> + +<P>The template for the gateway is different. Notice how it +reverses <VAR>left</VAR> and <VAR>right</VAR>, in keeping with our +convention that <STRONG>L</STRONG>eft is <STRONG>L</STRONG>ocal, +<STRONG>R</STRONG>ight <STRONG>R</STRONG>emote. Be sure to switch your +rsasigkeys in keeping with this.</P> + +<PRE> ssh2 xy.example.com + vi /etc/ipsec.conf</PRE> + +<P>and add:</P> + +<PRE>conn road + left=192.0.2.2 # Gateway's information + leftid=@xy.example.com # + leftsubnet=192.0.2.128/29 # + leftrsasigkey=0sAQOnwiBPt... # + rightnexthop=%defaultroute # correct in many situations + right=%any # Wildcard: we don't know the laptop's IP + rightid=@road.example.com # + rightrsasigkey=0sAQPIPN9uI... # + auto=add # authorizes but doesn't start this + # connection at startup</PRE> + + + +<H3>Start your connection</H3> + +<P>You must start the connection from the Road Warrior side. On your laptop, +type:</P> +<PRE> ipsec auto --start net-to-net</PRE> + +<P>You should see:</P> +<PRE>104 "net-net" #223: STATE_MAIN_I1: initiate +106 "road" #301: STATE_MAIN_I2: sent MI2, expecting MR2 +108 "road" #301: STATE_MAIN_I3: sent MI3, expecting MR3 +004 "road" #301: STATE_MAIN_I4: ISAKMP SA established +112 "road" #302: STATE_QUICK_I1: initiate +004 "road" #302: STATE_QUICK_I2: sent QI2, IPsec SA established</PRE> + +<P>Look for <VAR>IPsec SA established</VAR>. If you're +unsuccessful, see our +<A HREF="trouble.html#trouble">troubleshooting tips</A>.</P> + + + +<H3>Do not MASQ or NAT packets to be tunneled</H3> + +<P>If you are using <A HREF="glossary.html#masq">IP masquerade</A> or +<A HREF="glossary.html#NAT.gloss">Network Address Translation (NAT)</A> +on either gateway, +you must now exempt the packets you wish to tunnel from this treatment. +For example, if you have a rule like:</P> + +<PRE>iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE +</PRE> + +<P>change it to something like:</P> +<PRE>iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -d \! 192.0.2.128/29 -j MASQUERADE</PRE> + + +<H3>Test your connection</H3> + +<P>From your laptop, ping a subnet node behind the remote gateway. Do not +choose the gateway itself for this test.</P> + +<PRE> ping ns.winston.example.com</PRE> + +<P>Snoop the packets exiting the laptop, with a command like:</P> +<PRE> tcpdump -i wlan0</PRE> +<P>You have success if you see (Encapsulating Security Payload) packets +travelling <B>in both directions</B>:</P> + +<PRE> 19:16:32.046220 192.0.2.2 > 192.0.2.9: ESP(spi=0x3be6c4dc,seq=0x3) + 19:16:32.085630 192.0.2.9 > 192.0.2.2: ESP(spi=0x5fdd1cf8,seq=0x6)</PRE> + + +<P>If you do, great! Traffic between your Road Warrior and the net +behind your gateway is protected. +If not, see our +<A HREF="trouble.html#trouble">troubleshooting hints</A>.</P> + +<P>Your new tunnel protects only traffic addressed to the net, not to +the IPsec gateway itself. If you need the latter, you'll want to make an +<A HREF="adv_config.html#adv_config">extra tunnel.</A>.</P> + +<H3>Finishing touches</H3> + +<P>On both ends, name your connection wisely, like:</P> +<PRE>conn mike-to-office</PRE> +<P><B>On the laptop only,</B> replace</P> +<PRE> auto=add</PRE> +<P>with:</P> +<PRE> auto=start</PRE> +<P>so that you'll be connected on-boot.</P> +<P>Happy telecommuting!</P> + +<H3>Multiple Road Warriors</H3> + +<P>If you're using RSA keys, as we did in this example, you can add +as many Road Warriors as you like. The left/rightid +parameter lets Linux FreeS/WAN distinguish between multiple Road Warrior +peers, each with its own public key.</P> + +<P>The situation is different for shared secrets (PSK). During a +PSK negotiation, ID information is not available at the time Pluto +is trying to determine which secret to use, so, effectively, you can +only define one Roadwarrior connection. All your PSK road warriors +must therefore share one secret.</P> + + +<H2>What next?</H2> + +<P>Using the principles illustrated here, you can try variations such as: +<UL> +<LI>a telecommuter with a static IP</LI> +<LI>a road warrior with a subnet behind it</LI> +</UL> +<P>Or, look at some of our <A HREF="adv_config.html#adv_config">more complex configuration examples.</A>.</P> +</BODY> +</HTML> diff --git a/doc/src/crosscompile.html b/doc/src/crosscompile.html new file mode 100644 index 000000000..c488957c8 --- /dev/null +++ b/doc/src/crosscompile.html @@ -0,0 +1,105 @@ +<HTML>
+<HEAD>
+ <TITLE>Cross Compiling FreeS/WAN</TITLE>
+ <meta name="keywords" content="Linux, IPSEC, VPN, Security, FreeSWAN, cross, compile">
+<!--
+ Written by Ken Bantoft <ken@freeswan.ca> for the Linux FreeS/WAN project
+ Freely distributable under the GNU General Public License
+
+ More information at www.freeswan.org
+ Feedback to users@lists.freeswan.org
+
+CVS information:
+RCS ID: $Id: crosscompile.html,v 1.1 2004/03/15 20:35:24 as Exp $
+Last changed: $Date: 2004/03/15 20:35:24 $
+Revision number: $Revision: 1.1 $
+
+CVS revision numbers do not correspond to FreeS/WAN release numbers.
+-->
+
+</HEAD>
+<BODY>
+
+<H1><A NAME="guide"></A>Linux FreeS/WAN Cross Compiling Guide</H1>
+
+<H2><A NAME="overview"></A>Overview</H2>
+
+<P>
+This document provides general instructions on how to cross compile
+FreeS/WAN,
+that is - compile it for another architecture (eg: StrongARM)</P>
+<OL>
+ <LI><A HREF="#setup">Setting up your environment</A>.</LI>
+ <LI><A HREF="#building">Building</A>.</LI>
+ <LI><A HREF="#common">Common Problems</A>.</LI>
+</OL>
+<H2><A NAME="setup"></A>Setting up your Environment</H2>
+<H3>Enviroment Variables</H3>
+<P>There are a number of environment variables you can set to help facilitate
+cross compiling FreeS/WAN. All examples will are using the bash shell.
+</P>
+<P>The following is an example of the how to set the environment variables if
+you were cross compiling using the Embedix ARM toolchain, to build for an embedded
+device like the Sharp Zaurus. Set these while you are in the FreeS/WAN directory.
+It is often simpler to put the entire list into a script (eg: cross-setup.sh), and
+then "source cross-setup.sh" or similar.
+<pre>
+export ARCH=arm
+export CC=/opt/Embedix/tools/bin/arm-linux-gcc
+export LD=/opt/Embedix/tools/bin/arm-linux-ld
+export RANLIB=/opt/Embedix/tools/bin/arm-linux-ranlib
+export AR=/opt/Embedix/tools/bin/arm-linux-ar
+export AS=/opt/Embedix/tools/bin/arm-linux-as
+export STRIP=/opt/Embedix/tools/bin/arm-linux-strip
+export KERNELSRC=/zaurus/kernel-2.4.6
+export LD_LIBRARY_PATH=/opt/Embedix/tools/lib/gcc-lib/arm-linux/2.95.2/
+export PATH=$PATH:/opt/Embedix/tools/bin
+export DESTDIR=/zaurus/binaries
+</pre>
+In the example above, we setup all of the usual gcc + bin-utils programs,
+as well as setting the LD_LIBRARY_PATH to our cross-compiled system libraries,
+and DESTDIR to our output directory.
+</P>
+
+<H3>Kernel Source</H3>
+<P>Place a copy of the kernel source, setup for your target device somewhere on
+your filesystem and set KERNELSRC= to this directory. You will need to prepare
+your kernel source treefirst, by running "make menuconfig && make dep && make
+modules". Once this is done, you can move on to building FreeS/WAN</P>
+
+<H2><A NAME="building"></A>Building</H2>
+<H3>The Make Process</H3>
+<P>There are two parts to building FreeS/WAN - the userland programs and utilities,
+and the ipsec.o kernel module. Each can be built seperatly, making debugging the
+build process simpler.
+</P>
+<P>Step 1 is to run "make programs". This will build the required libs
+(libfreeswan.a) as well as all of the userland tools (pluto, whack, etc...).
+Provided your environment variables are set correctly, you should see the output
+using your specified gcc (arm-linux-gcc for our example), ld, as, ar and
+ranlib.</P>
+<P>If this completes successfully, you can run "make install" to install a copy of
+all of the binaries, man pages and other documentation to DESTDIR.</P>
+<P>Step 2 is to build the ipsec.o module. This is done with "make oldmod", which
+should change into the KERNELSRC directory and then compile and link the required
+files to generate an ipsec.o file. If this is successful, you will end up with an
+ipsec.o file in your FreeS/WAN directory, under linux/net/ipsec/.</P>
+<P>Remember to install this to /lib/modules/$kernelversion/kernel/net/ipsec/ on
+your target machine.</P>
+
+
+
+<H2><A NAME="common"></A>Common Problems Building</H2>
+<P>Here is a list of common problems/errors you may run into when cross compiling
+FreeS/WAN.</P>
+<UL>
+<LI>gmp.h, libgmp not found, error with -lgmp. All of these refer to the GNU Math
+Precision Library. You will need to have already built this for your target
+system. Place libgmp.so in LD_LIBRARY_PATH, and ensure the headers are in your
+include path as well.
+</UL>
+
+<P><BR><BR>
+</P>
+</BODY>
+</HTML>
diff --git a/doc/src/draft-richardson-ipsec-opportunistic.html b/doc/src/draft-richardson-ipsec-opportunistic.html new file mode 100644 index 000000000..87a13365a --- /dev/null +++ b/doc/src/draft-richardson-ipsec-opportunistic.html @@ -0,0 +1,2456 @@ +<html><head><title>Opportunistic Encryption using The Internet Key Exchange (IKE)</title> +<STYLE type='text/css'> + .title { color: #990000; font-size: 22px; line-height: 22px; font-weight: bold; text-align: right; + font-family: helvetica, arial, sans-serif } + .filename { color: #666666; font-size: 18px; line-height: 28px; font-weight: bold; text-align: right; + font-family: helvetica, arial, sans-serif } + p.copyright { color: #000000; font-size: 10px; + font-family: verdana, charcoal, helvetica, arial, sans-serif } + p { margin-left: 2em; margin-right: 2em; } + li { margin-left: 3em; } + ol { margin-left: 2em; margin-right: 2em; } + ul.text { margin-left: 2em; margin-right: 2em; } + pre { margin-left: 3em; color: #333333 } + ul.toc { color: #000000; line-height: 16px; + font-family: verdana, charcoal, helvetica, arial, sans-serif } + H3 { color: #333333; font-size: 16px; line-height: 16px; font-family: helvetica, arial, sans-serif } + H4 { color: #000000; font-size: 14px; font-family: helvetica, arial, sans-serif } + TD.header { color: #ffffff; font-size: 10px; font-family: arial, helvetica, san-serif; valign: top } + TD.author-text { color: #000000; font-size: 10px; + font-family: verdana, charcoal, helvetica, arial, sans-serif } + TD.author { color: #000000; font-weight: bold; margin-left: 4em; font-size: 10px; font-family: verdana, charcoal, helvetica, arial, sans-serif } + A:link { color: #990000; font-weight: bold; + font-family: MS Sans Serif, verdana, charcoal, helvetica, arial, sans-serif } + A:visited { color: #333333; font-weight: bold; + font-family: MS Sans Serif, verdana, charcoal, helvetica, arial, sans-serif } + A:name { color: #333333; font-weight: bold; + font-family: MS Sans Serif, verdana, charcoal, helvetica, arial, sans-serif } + .link2 { color:#ffffff; font-weight: bold; text-decoration: none; + font-family: monaco, charcoal, geneva, MS Sans Serif, helvetica, monotype, verdana, sans-serif; + font-size: 9px } + .RFC { color:#666666; font-weight: bold; text-decoration: none; + font-family: monaco, charcoal, geneva, MS Sans Serif, helvetica, monotype, verdana, sans-serif; + font-size: 9px } + .hotText { color:#ffffff; font-weight: normal; text-decoration: none; + font-family: charcoal, monaco, geneva, MS Sans Serif, helvetica, monotype, verdana, sans-serif; + font-size: 9px } +</style> +</head> +<body bgcolor="#ffffff" text="#000000" alink="#000000" vlink="#666666" link="#990000"> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<table width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table width="100%" border="0" cellpadding="2" cellspacing="1"> +<tr valign="top"><td width="33%" bgcolor="#666666" class="header">Independent submission</td><td width="33%" bgcolor="#666666" class="header">M. Richardson</td></tr> +<tr valign="top"><td width="33%" bgcolor="#666666" class="header">Internet-Draft</td><td width="33%" bgcolor="#666666" class="header">SSW</td></tr> +<tr valign="top"><td width="33%" bgcolor="#666666" class="header">Expires: November 19, 2003</td><td width="33%" bgcolor="#666666" class="header">D. Redelmeier</td></tr> +<tr valign="top"><td width="33%" bgcolor="#666666" class="header"> </td><td width="33%" bgcolor="#666666" class="header">Mimosa</td></tr> +<tr valign="top"><td width="33%" bgcolor="#666666" class="header"> </td><td width="33%" bgcolor="#666666" class="header">May 21, 2003</td></tr> +</table></td></tr></table> +<div align="right"><font face="monaco, MS Sans Serif" color="#990000" size="+3"><b><br><span class="title">Opportunistic Encryption using The Internet Key Exchange (IKE)</span></b></font></div> +<div align="right"><font face="monaco, MS Sans Serif" color="#666666" size="+2"><b><span class="filename">draft-richardson-ipsec-opportunistic-11.txt</span></b></font></div> +<font face="verdana, helvetica, arial, sans-serif" size="2"> + +<h3>Status of this Memo</h3> +<p> +This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.</p> +<p> +Internet-Drafts are working documents of the Internet Engineering +Task Force (IETF), its areas, and its working groups. +Note that other groups may also distribute working documents as +Internet-Drafts.</p> +<p> +Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any time. +It is inappropriate to use Internet-Drafts as reference material or to cite +them other than as "work in progress."</p> +<p> +The list of current Internet-Drafts can be accessed at +<a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p> +<p> +The list of Internet-Draft Shadow Directories can be accessed at +<a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p> +<p> +This Internet-Draft will expire on November 19, 2003.</p> + +<h3>Copyright Notice</h3> +<p> +Copyright (C) The Internet Society (2003). All Rights Reserved.</p> + +<h3>Abstract</h3> + +<p> +This document describes opportunistic encryption (OE) using the Internet Key +Exchange (IKE) and IPsec. +Each system administrator adds new +resource records to his or her Domain Name System (DNS) to support +opportunistic encryption. The objective is to allow encryption for secure communication without +any pre-arrangement specific to the pair of systems involved. + +</p> +<p> +DNS is used to distribute the public keys of each +system involved. This is resistant to passive attacks. The use of DNS +Security (DNSSEC) secures this system against active attackers as well. + +</p> +<p> +As a result, the administrative overhead is reduced +from the square of the number of systems to a linear dependence, and it becomes +possible to make secure communication the default even +when the partner is not known in advance. + +</p> +<p> +This document is offered up as an Informational RFC. + +</p><a name="toc"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Table of Contents</h3> +<ul compact class="toc"> +<b><a href="#anchor1">1.</a> +Introduction<br></b> +<b><a href="#anchor6">2.</a> +Overview<br></b> +<b><a href="#anchor13">3.</a> +Specification<br></b> +<b><a href="#anchor31">4.</a> +Impacts on IKE<br></b> +<b><a href="#anchor38">5.</a> +DNS issues<br></b> +<b><a href="#anchor42">6.</a> +Network address translation interaction<br></b> +<b><a href="#anchor46">7.</a> +Host implementations<br></b> +<b><a href="#anchor47">8.</a> +Multi-homing<br></b> +<b><a href="#anchor48">9.</a> +Failure modes<br></b> +<b><a href="#anchor52">10.</a> +Unresolved issues<br></b> +<b><a href="#anchor54">11.</a> +Examples<br></b> +<b><a href="#securityconsiderations">12.</a> +Security considerations<br></b> +<b><a href="#anchor79">13.</a> +IANA Considerations<br></b> +<b><a href="#anchor80">14.</a> +Acknowledgments<br></b> +<b><a href="#rfc.references1">§</a> +Normative references<br></b> +<b><a href="#rfc.authors">§</a> +Authors' Addresses<br></b> +<b><a href="#rfc.copyright">§</a> +Full Copyright Statement<br></b> +</ul> +<br clear="all"> + +<a name="anchor1"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.1"></a><h3>1. Introduction</h3> + +<a name="rfc.section.1.1"></a><h4><a name="anchor2">1.1</a> Motivation</h4> + +<p> +The objective of opportunistic encryption is to allow encryption without +any pre-arrangement specific to the pair of systems involved. Each +system administrator adds +public key information to DNS records to support opportunistic +encryption and then enables this feature in the nodes' IPsec stack. +Once this is done, any two such nodes can communicate securely. + +</p> +<p> +This document describes opportunistic encryption as designed and +mostly implemented by the Linux FreeS/WAN project. +For project information, see http://www.freeswan.org. + +</p> +<p> +The Internet Architecture Board (IAB) and Internet Engineering +Steering Group (IESG) have taken a strong stand that the Internet +should use powerful encryption to provide security and +privacy <a href="#RFC1984">[4]</a>. +The Linux FreeS/WAN project attempts to provide a practical means to implement this policy. + +</p> +<p> +The project uses the IPsec, ISAKMP/IKE, DNS and DNSSEC +protocols because they are +standardized, widely available and can often be deployed very easily +without changing hardware or software or retraining users. + +</p> +<p> +The extensions to support opportunistic encryption are simple. No +changes to any on-the-wire formats are needed. The only changes are to +the policy decision making system. This means that opportunistic +encryption can be implemented with very minimal changes to an existing +IPsec implementation. + +</p> +<p> +Opportunistic encryption creates a "fax effect". The proliferation +of the fax machine was possible because it did not require that everyone +buy one overnight. Instead, as each person installed one, the value +of having one increased - as there were more people that could receive faxes. +Once opportunistic encryption is installed it +automatically recognizes +other boxes using opportunistic encryption, without any further configuration +by the network +administrator. So, as opportunistic encryption software is installed on more +boxes, its value +as a tool increases. + +</p> +<p> +This document describes the infrastructure to permit deployment of +Opportunistic Encryption. + +</p> +<p> +The term S/WAN is a trademark of RSA Data Systems, and is used with permission +by this project. + +</p> +<a name="rfc.section.1.2"></a><h4><a name="anchor3">1.2</a> Types of network traffic</h4> + +<p> + To aid in understanding the relationship between security processing and IPsec + we divide network traffic into four categories: + +<blockquote class="text"><dl> +<dt>* Deny:</dt> +<dd> networks to which traffic is always forbidden. +</dd> +<dt>* Permit:</dt> +<dd> networks to which traffic in the clear is permitted. +</dd> +<dt>* Opportunistic tunnel:</dt> +<dd> networks to which traffic is encrypted if possible, but otherwise is in the clear + or fails depending on the default policy in place. + +</dd> +<dt>* Configured tunnel:</dt> +<dd> networks to which traffic must be encrypted, and traffic in the clear is never permitted. +</dd> +</dl></blockquote><p> +</p> +<p> +Traditional firewall devices handle the first two categories. No authentication is required. +The permit policy is currently the default on the Internet. + +</p> +<p> +This document describes the third category - opportunistic tunnel, which is +proposed as the new default for the Internet. + +</p> +<p> + Category four, encrypt traffic or drop it, requires authentication of the + end points. As the number of end points is typically bounded and is typically + under a single authority, arranging for distribution of + authentication material, while difficult, does not require any new + technology. The mechanism described here provides an additional way to + distribute the authentication materials, that of a public key method that does not + require deployment of an X.509 based infrastructure. + +</p> +<p> +Current Virtual Private Networks can often be replaced by an "OE paranoid" +policy as described herein. + +</p> +<a name="rfc.section.1.3"></a><h4><a name="anchor4">1.3</a> Peer authentication in opportunistic encryption</h4> + +<p> + Opportunistic encryption creates tunnels between nodes that + are essentially strangers. This is done without any prior bilateral + arrangement. + There is, therefore, the difficult question of how one knows to whom one is + talking. + +</p> +<p> + One possible answer is that since no useful + authentication can be done, none should be tried. This mode of operation is + named "anonymous encryption". An active man-in-the-middle attack can be + used to thwart the privacy of this type of communication. + Without peer authentication, there is no way to prevent this kind of attack. + +</p> +<p> +Although a useful mode, anonymous encryption is not the goal of this +project. Simpler methods are available that can achieve anonymous +encryption only, but authentication of the peer is a desireable goal. +The latter is achieved through key distribution in DNS, leveraging upon +the authentication of the DNS in DNSSEC. + +</p> +<p> + Peers are, therefore, authenticated with DNSSEC when available. Local policy +determines how much trust to extend when DNSSEC is not available. + +</p> +<p> + However, an essential premise of building private connections with + strangers is that datagrams received through opportunistic tunnels + are no more special than datagrams that arrive in the clear. + Unlike in a VPN, these datagrams should not be given any special + exceptions when it comes to auditing, further authentication or + firewalling. + +</p> +<p> + When initiating outbound opportunistic encryption, local + configuration determines what happens if tunnel setup fails. It may be that + the packet goes out in the clear, or it may be dropped. + +</p> +<a name="rfc.section.1.4"></a><h4><a name="anchor5">1.4</a> Use of RFC2119 terms</h4> + +<p> + The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, + SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this + document, are to be interpreted as described in <a href="#RFC2119">[5]</a> +</p> +<a name="anchor6"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.2"></a><h3>2. Overview</h3> + +<a name="rfc.section.2.1"></a><h4><a name="anchor7">2.1</a> Reference diagram</h4> +<br><hr size="1" shade="0"> +<a name="networkdiagram"></a> + +<p>The following network diagram is used in the rest of + this document as the canonical diagram: +</p></font><pre> + [Q] [R] + . . AS2 + [A]----+----[SG-A].......+....+.......[SG-B]-------[B] + | ...... + AS1 | ..PI.. + | ...... + [D]----+----[SG-D].......+....+.......[C] AS3 + + + </pre><font face="verdana, helvetica, arial, sans-serif" size="2"> + +<p> +</p><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Reference Network Diagram </b></font><br></td></tr></table><hr size="1" shade="0"> + +<p> + In this diagram, there are four end-nodes: A, B, C and D. + There are three gateways, SG-A, SG-B, SG-D. A, D, SG-A and SG-D are part + of the same administrative authority, AS1. SG-A and SG-D are on two different exit + paths from organization 1. SG-B/B is an independent organization, AS2. + Nodes Q and R are nodes on the Internet. PI is the Public + Internet ("The Wild"). + +</p> +<a name="rfc.section.2.2"></a><h4><a name="anchor8">2.2</a> Terminology</h4> + +<p> + The following terminology is used in this document: + +</p> +<blockquote class="text"><dl> +<dt>Security gateway:</dt> +<dd> a system that performs IPsec tunnel + mode encapsulation/decapsulation. [SG-x] in the diagram. +</dd> +<dt>Alice:</dt> +<dd> node [A] in the diagram. When an IP address is needed, this is 192.1.0.65. +</dd> +<dt>Bob:</dt> +<dd> node [B] in the diagram. When an IP address is needed, this is 192.2.0.66. +</dd> +<dt>Carol:</dt> +<dd> node [C] in the diagram. When an IP address is needed, this is 192.1.1.67. +</dd> +<dt>Dave:</dt> +<dd> node [D] in the diagram. When an IP address is needed, this is 192.3.0.68. +</dd> +<dt>SG-A:</dt> +<dd> Alice's security gateway. Internally it is 192.1.0.1, externally it is 192.1.1.4. +</dd> +<dt>SG-B:</dt> +<dd> Bob's security gateway. Internally it is 192.2.0.1, externally it is 192.1.1.5. +</dd> +<dt>SG-D:</dt> +<dd> Dave's security gateway. Also Alice's backup security gateway. Internally it is 192.3.0.1, externally it is 192.1.1.6. +</dd> +<dt>-</dt> +<dd> A single dash represents clear-text datagrams. +</dd> +<dt>=</dt> +<dd> An equals sign represents phase 2 (IPsec) cipher-text + datagrams. +</dd> +<dt>~</dt> +<dd> A single tilde represents clear-text phase 1 datagrams. +</dd> +<dt>#</dt> +<dd> A hash sign represents phase 1 (IKE) cipher-text + datagrams. +</dd> +<dt>.</dt> +<dd> A period represents an untrusted network of unknown + type. +</dd> +<dt>Configured tunnel:</dt> +<dd> a tunnel that + is directly and deliberately hand configured on participating gateways. + Configured tunnels are typically given a higher level of + trust than opportunistic tunnels. +</dd> +<dt>Road warrior tunnel:</dt> +<dd> a configured tunnel connecting one + node with a fixed IP address and one node with a variable IP address. + A road warrior (RW) connection must be initiated by the + variable node, since the fixed node cannot know the + current address for the road warrior. +</dd> +<dt>Anonymous encryption:</dt> +<dd> + the process of encrypting a session without any knowledge of who the + other parties are. No authentication of identities is done. +</dd> +<dt>Opportunistic encryption:</dt> +<dd> + the process of encrypting a session with authenticated knowledge of + who the other parties are. +</dd> +<dt>Lifetime:</dt> +<dd> + the period in seconds (bytes or datagrams) for which a security + association will remain alive before needing to be re-keyed. +</dd> +<dt>Lifespan:</dt> +<dd> + the effective time for which a security association remains useful. A + security association with a lifespan shorter than its lifetime would + be removed when no longer needed. A security association with a + lifespan longer than its lifetime would need to be re-keyed one or + more times. +</dd> +<dt>Phase 1 SA:</dt> +<dd> an ISAKMP/IKE security association sometimes + referred to as a keying channel. +</dd> +<dt>Phase 2 SA:</dt> +<dd> an IPsec security association. +</dd> +<dt>Tunnel:</dt> +<dd> another term for a set of phase 2 SA (one in each direction). +</dd> +<dt>NAT:</dt> +<dd> Network Address Translation + (see <a href="#RFC2663">[20]</a>). +</dd> +<dt>NAPT:</dt> +<dd> Network Address and Port Translation + (see <a href="#RFC2663">[20]</a>). +</dd> +<dt>AS:</dt> +<dd> an autonomous system (AS) is a group of systems (a network) that + are under the administrative control of a single organization. +</dd> +<dt>Default-free zone:</dt> +<dd> + a set of routers that maintain a complete set of routes to + all currently reachable destinations. Having such a list, these routers + never make use of a default route. A datagram with a destination address + not matching any route will be dropped by such a router. + +</dd> +</dl></blockquote><p> +<a name="rfc.section.2.3"></a><h4><a name="anchor9">2.3</a> Model of operation</h4> + +<p> +The opportunistic encryption security gateway (OE gateway) is a regular +gateway node as described in <a href="#RFC0791">[2]</a> section 2.4 and +<a href="#RFC1009">[3]</a> with the additional capabilities described here and +in <a href="#RFC2401">[7]</a>. +The algorithm described here provides a way to determine, for each datagram, +whether or not to encrypt and tunnel the datagram. Two important things +that must be determined are whether or not to encrypt and tunnel and, if +so, the destination address or name of the tunnel end point which should be used. + +</p> +<a name="rfc.section.2.3.1"></a><h4><a name="anchor10">2.3.1</a> Tunnel authorization</h4> + +<p> +The OE gateway determines whether or not to create a tunnel based on +the destination address of each packet. Upon receiving a packet with a destination +address not recently seen, the OE gateway performs a lookup in DNS for an +authorization resource record (see <a href="#TXT">Use of TXT delegation record</a>). The record is located using +the IP address to perform a search in the in-addr.arpa (IPv4) or ip6.arpa +(IPv6) maps. If an authorization record is found, the OE gateway +interprets this as a request for a tunnel to be formed. + +</p> +<a name="rfc.section.2.3.2"></a><h4><a name="anchor11">2.3.2</a> Tunnel end-point discovery</h4> + +<p> +The authorization resource record also provides the address or name of the tunnel +end point which should be used. + +</p> +<p> +The record may also provide the public RSA key of the tunnel end point +itself. This is provided for efficiency only. If the public RSA key is not +present, the OE gateway performs a second lookup to find a KEY +resource record for the end point address or name. + +</p> +<p> +Origin and integrity protection of the resource records is provided by +DNSSEC (<a href="#RFC2535">[16]</a>). <a href="#nodnssec">Restriction on unauthenticated TXT delegation records</a> +documents an optional restriction on the tunnel end point if DNSSEC signatures +are not available for the relevant records. + +</p> +<a name="rfc.section.2.3.3"></a><h4><a name="anchor12">2.3.3</a> Caching of authorization results</h4> + +<p> +The OE gateway maintains a cache, in the forwarding plane, of +source/destination pairs for which opportunistic encryption has been +attempted. This cache maintains a record of whether or not OE was +successful so that subsequent datagrams can be forwarded properly +without additional delay. + +</p> +<p> +Successful negotiation of OE instantiates a new security association. +Failure to negotiate OE results in creation of a +forwarding policy entry either to drop or transmit in the clear future +datagrams. This negative cache is necessary to avoid the possibly lengthy process of repeatedly looking +up the same information. + +</p> +<p> +The cache is timed out periodically, as described in <a href="#teardown">Renewal and teardown</a>. +This removes entries that are no longer +being used and permits the discovery of changes in authorization policy. + +</p> +<a name="anchor13"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.3"></a><h3>3. Specification</h3> + +<p> +The OE gateway is modeled to have a forwarding plane and a control +plane. A control channel, such as PF_KEY, connects the two planes. +(See <a href="#RFC2367">[6]</a>.) +The forwarding plane performs per datagram operations. The control plane +contains a keying +daemon, such as ISAKMP/IKE, and performs all authorization, peer authentication and +key derivation functions. + +</p> +<a name="rfc.section.3.1"></a><h4><a name="anchor14">3.1</a> Datagram state machine</h4> + +<p> +Let the OE gateway maintain a collection of objects -- a superset of the +security policy database (SPD) specified in <a href="#RFC2401">[7]</a>. For +each combination of source and destination address, an SPD +object exists in one of five following states. +Prior to forwarding each datagram, the +responder uses the source and destination addresses to pick an entry from the SPD. +The SPD then determines if and how the packet is forwarded. + +</p> +<a name="rfc.section.3.1.1"></a><h4><a name="anchor15">3.1.1</a> Non-existent policy</h4> + +<p> +If the responder does not find an entry, then this policy applies. +The responder creates an entry with an initial state of "hold policy" and requests +keying material from the keying daemon. The responder does not forward the datagram, +rather it attaches the datagram to the SPD entry as the "first" datagram and retains it +for eventual transmission in a new state. + + +</p> +<a name="rfc.section.3.1.2"></a><h4><a name="anchor16">3.1.2</a> Hold policy</h4> + +<p> +The responder requests keying material. If the interface to the keying +system is lossy (PF_KEY, for instance, can be), the implementation +SHOULD include a mechanism to retransmit the +keying request at a rate limited to less than 1 request per second. +The responder does not forward the datagram. It attaches the +datagram to the SPD entry as the "last" datagram where it is retained +for eventual transmission. If there is +a datagram already so stored, then that already stored datagram is discarded. + +</p> +<p> +Because the "first" datagram is probably a TCP SYN packet, the +responder retains the "first" datagram in an attempt to avoid waiting for a +TCP retransmit. The responder retains the "last" +datagram in deference to streaming protocols that find it useful to know +how much data has been lost. These are recommendations to +decrease latency. There are no operational requirements for this. + +</p> +<a name="rfc.section.3.1.3"></a><h4><a name="anchor17">3.1.3</a> Pass-through policy</h4> + +<p> +The responder forwards the datagram using the normal forwarding table. +The responder enters this state only by command from the keying daemon, +and upon entering this state, also forwards the "first" and "last" datagrams. + +</p> +<a name="rfc.section.3.1.4"></a><h4><a name="anchor18">3.1.4</a> Deny policy</h4> + +<p> +The responder discards the datagram. The responder enters this state only by +command +from the keying daemon, and upon entering this state, discards the "first" +and "last" datagrams. +Local administration decides if further datagrams cause ICMP messages +to be generated (i.e. ICMP Destination Unreachable, Communication +Administratively Prohibited. type=3, code=13). + +</p> +<a name="rfc.section.3.1.5"></a><h4><a name="anchor19">3.1.5</a> Encrypt policy</h4> + +<p> +The responder encrypts the datagram using the indicated security association database +(SAD) entry. The responder enters this state only by command from the keying daemon, and upon entering +this state, releases and forwards the "first" and "last" datagrams using the +new encrypt policy. + +</p> +<p> +If the associated SAD entry expires because of byte, packet or time limits, then +the entry returns to the Hold policy, and an expire message is sent to the keying daemon. + +</p> +<p> +All states may be created directly by the keying daemon while acting as a +responder. + +</p> +<a name="rfc.section.3.2"></a><h4><a name="initclasses">3.2</a> Keying state machine - initiator</h4> + +<p> +Let the keying daemon maintain a collection of objects. Let them be +called "connections" or "conn"s. There are two categories of +connection objects: classes and instances. A class represents an +abstract policy - what could be. An instance represents an actual connection - +what is implemented at the time. + +</p> +<p> +Let there be two further subtypes of connections: keying channels (Phase +1 SAs) and data channels (Phase 2 SAs). Each data channel object may have +a corresponding SPD and SAD entry maintained by the datagram state machine. + +</p> +<p> +For the purposes of opportunistic encryption, there MUST, at least, be +connection classes known as "deny", "always-clear-text", "OE-permissive", and +"OE-paranoid". +The latter two connection classes define a set of source and/or destination +addresses for which opportunistic encryption will be attempted. The administrator MAY set policy +options in a number of additional places. An implementation MAY create additional connection classes to further refine +these policies. + +</p> +<p> +The simplest system may need only the "OE-permissive" connection, and would +list its own (single) IP address as the source address of this policy and +the wild-card address 0.0.0.0/0 as the destination IPv4 address. That is, the +simplest policy is to try opportunistic encryption with all destinations. + +</p> +<p> +The distinction between permissive and paranoid OE use will become clear +in the state transition differences. In general a permissive OE will, on +failure, install a pass-through policy, while a paranoid OE will, on failure, +install a drop policy. + +</p> +<p> +In this description of the keying machine's state transitions, the states +associated with the keying system itself are omitted because they are best documented in the keying system +(<a href="#RFC2407">[8]</a>, +<a href="#RFC2408">[9]</a> and <a href="#RFC2409">[10]</a> for ISAKMP/IKE), +and the details are keying system specific. Opportunistic encryption is not +dependent upon any specific keying protocol, but this document does provide +requirements for those using ISAKMP/IKE to assure that implementations inter-operate. + +</p> +<p> +The state transitions that may be involved in communicating with the +forwarding plane are omitted. PF_KEY and similar protocols have their own +set of states required for message sends and completion notifications. + +</p> +<p> +Finally, the retransmits and recursive lookups that are normal for DNS are +not included in this description of the state machine. + +</p> +<a name="rfc.section.3.2.1"></a><h4><a name="anchor20">3.2.1</a> Nonexistent connection</h4> + +<p> +There is no connection instance for a given source/destination address pair. +Upon receipt of a request for keying material for this +source/destination pair, the initiator searches through the connection classes to +determine the most appropriate policy. Upon determining an appropriate +connection class, an instance object is created of that type. +Both of the OE types result in a potential OE connection. + +</p> +<p>Failure to find an appropriate connection class results in an +administrator defined default. + +</p> +<p> +In each case, when the initiator finds an appropriate class for the new flow, +an instance connection is made of the class which matched. + +</p> +<a name="rfc.section.3.2.2"></a><h4><a name="anchor21">3.2.2</a> Clear-text connection</h4> + +<p> +The non-existent connection makes a transition to this state when an +always-clear-text class is instantiated, or when an OE-permissive +connection fails. During the transition, the initiator creates a pass-through +policy object in the forwarding plane for the appropriate flow. + +</p> +<p> +Timing out is the only way to leave this state +(see <a href="#expiring">Expiring connection</a>). + +</p> +<a name="rfc.section.3.2.3"></a><h4><a name="anchor22">3.2.3</a> Deny connection</h4> + +<p> +The empty connection makes a transition to this state when a +deny class is instantiated, or when an OE-paranoid connection fails. +During the transition, the initiator creates a deny policy object in the forwarding plane +for the appropriate flow. + +</p> +<p> +Timing out is the only way to leave this state +(see <a href="#expiring">Expiring connection</a>). + +</p> +<a name="rfc.section.3.2.4"></a><h4><a name="anchor23">3.2.4</a> Potential OE connection</h4> + +<p> +The empty connection makes a transition to this state when one of either OE class is instantiated. +During the transition to this state, the initiator creates a hold policy object in the +forwarding plane for the appropriate flow. + +</p> +<p> +In addition, when making a transition into this state, DNS lookup is done in +the reverse-map for a TXT delegation resource record (see <a href="#TXT">Use of TXT delegation record</a>). +The lookup key is the destination address of the flow. + +</p> +<p> +There are three ways to exit this state: + +<ol class="text"> +<li>DNS lookup finds a TXT delegation resource record. +</li> +<li>DNS lookup does not find a TXT delegation resource record. +</li> +<li>DNS lookup times out. +</li> +</ol><p> +</p> +<p> +Based upon the results of the DNS lookup, the potential OE connection makes a +transition to the pending OE connection state. The conditions for a +successful DNS look are: + +<ol class="text"> +<li>DNS finds an appropriate resource record +</li> +<li>It is properly formatted according to <a href="#TXT">Use of TXT delegation record</a> +</li> +<li> if DNSSEC is enabled, then the signature has been vouched for. +</li> +</ol><p> + +Note that if the initiator does not find the public key +present in the TXT delegation record, then the public key must +be looked up as a sub-state. Only successful completion of all the +DNS lookups is considered a success. + +</p> +<p> +If DNS lookup does not find a resource record or DNS times out, then the +initiator considers the receiver not OE capable. If this is an OE-paranoid instance, +then the potential OE connection makes a transition to the deny connection state. +If this is an OE-permissive instance, then the potential OE connection makes a transition to the +clear-text connection state. + +</p> +<p> +If the initiator finds a resource record but it is not properly formatted, or +if DNSSEC is +enabled and reports a failure to authenticate, then the potential OE +connection should make a +transition to the deny connection state. This action SHOULD be logged. If the +administrator wishes to override this transition between states, then an +always-clear class can be installed for this flow. An implementation MAY make +this situation a new class. + +</p> +<a name="rfc.section.3.2.4.1"></a><h4><a name="nodnssec">3.2.4.1</a> Restriction on unauthenticated TXT delegation records</h4> + +<p> +An implementation SHOULD also provide an additional administrative control +on delegation records and DNSSEC. This control would apply to delegation +records (the TXT records in the reverse-map) that are not protected by +DNSSEC. +Records of this type are only permitted to delegate to their own address as +a gateway. When this option is enabled, an active attack on DNS will be +unable to redirect packets to other than the original destination. + +</p> +<a name="rfc.section.3.2.5"></a><h4><a name="anchor24">3.2.5</a> Pending OE connection</h4> + +<p> +The potential OE connection makes a transition to this state when +the initiator determines that all the information required from the DNS lookup is present. +Upon entering this state, the initiator attempts to initiate keying to the gateway +provided. + +</p> +<p> +Exit from this state occurs either with a successfully created IPsec SA, or +with a failure of some kind. Successful SA creation results in a transition +to the key connection state. + +</p> +<p> +Three failures have caused significant problems. They are clearly not the +only possible failures from keying. + +</p> +<p> +Note that if there are multiple gateways available in the TXT delegation +records, then a failure can only be declared after all have been +tried. Further, creation of a phase 1 SA does not constitute success. A set +of phase 2 SAs (a tunnel) is considered success. + +</p> +<p> +The first failure occurs when an ICMP port unreachable is consistently received +without any other communication, or when there is silence from the remote +end. This usually means that either the gateway is not alive, or the +keying daemon is not functional. For an OE-permissive connection, the initiator makes a transition +to the clear-text connection but with a low lifespan. For an OE-pessimistic connection, +the initiator makes a transition to the deny connection again with a low lifespan. The lifespan in both +cases is kept low because the remote gateway may +be in the process of rebooting or be otherwise temporarily unavailable. + +</p> +<p> +The length of time to wait for the remote keying daemon to wake up is +a matter of some debate. If there is a routing failure, 5 minutes is usually long enough for the network to +re-converge. Many systems can reboot in that amount of +time as well. However, 5 minutes is far too long for most users to wait to +hear that they can not connect using OE. Implementations SHOULD make this a +tunable parameter. + +</p> +<p> +The second failure occurs after a phase 1 SA has been created, but there is +either no response to the phase 2 proposal, or the initiator receives a +negative notify (the notify must be +authenticated). The remote gateway is not prepared to do OE at this time. +As before, the initiator makes a transition to the clear-text or the deny +connection based upon connection class, but this +time with a normal lifespan. + +</p> +<p> +The third failure occurs when there is signature failure while authenticating +the remote gateway. This can occur when there has been a +key roll-over, but DNS has not caught up. In this case again, the initiator makes a +transition to the clear-text or the deny connection based +upon the connection class. However, the lifespan depends upon the remaining +time to live in the DNS. (Note that DNSSEC signed resource records have a different +expiry time than non-signed records.) + +</p> +<a name="rfc.section.3.2.6"></a><h4><a name="keyed">3.2.6</a> Keyed connection</h4> + +<p> +The pending OE connection makes a transition to this state when +session keying material (the phase 2 SAs) is derived. The initiator creates an encrypt +policy in the forwarding plane for this flow. + +</p> +<p> +There are three ways to exit this state. The first is by receipt of an +authenticated delete message (via the keying channel) from the peer. This is +normal teardown and results in a transition to the expired connection state. + +</p> +<p> +The second exit is by expiry of the forwarding plane keying material. This +starts a re-key operation with a transition back to pending OE +connection. In general, the soft expiry occurs with sufficient time left +to continue to use the keys. A re-key can fail, which may +result in the connection failing to clear-text or deny as +appropriate. In the event of a failure, the forwarding plane +policy does not change until the phase 2 SA (IPsec SA) reaches its +hard expiry. + +</p> +<p> +The third exit is in response to a negotiation from a remote +gateway. If the forwarding plane signals the control plane that it has received an +unknown SPI from the remote gateway, or an ICMP is received from the remote gateway +indicating an unknown SPI, the initiator should consider that +the remote gateway has rebooted or restarted. Since these +indications are easily forged, the implementation must +exercise care. The initiator should make a cautious +(rate-limited) attempt to re-key the connection. + +</p> +<a name="rfc.section.3.2.7"></a><h4><a name="expiring">3.2.7</a> Expiring connection</h4> + +<p> +The initiator will periodically place each of the deny, clear-text, and keyed +connections into this +sub-state. See <a href="#teardown">Renewal and teardown</a> for more details of how often this +occurs. +The initiator queries the forwarding plane for last use time of the +appropriate +policy. If the last use time is relatively recent, then the connection +returns to the +previous deny, clear-text or keyed connection state. If not, then the +connection enters +the expired connection state. + +</p> +<p> +The DNS query and answer that lead to the expiring connection state are also +examined. The DNS query may become stale. (A negative, i.e. no such record, answer +is valid for the period of time given by the MINIMUM field in an attached SOA +record. See <a href="#RFC1034">[12]</a> section 4.3.4.) +If the DNS query is stale, then a new query is made. If the results change, then the connection +makes a transition to a new state as described in potential OE connection state. + +</p> +<p> +Note that when considering how stale a connection is, both outgoing SPD and +incoming SAD must be queried as some flows may be unidirectional for some time. + +</p> +<p> +Also note that the policy at the forwarding plane is not updated unless there +is a conclusion that there should be a change. + +</p> +<a name="rfc.section.3.2.8"></a><h4><a name="anchor25">3.2.8</a> Expired connection</h4> + +<p> +Entry to this state occurs when no datagrams have been forwarded recently via the +appropriate SPD and SAD objects. The objects in the forwarding plane are +removed (logging any final byte and packet counts if appropriate) and the +connection instance in the keying plane is deleted. + +</p> +<p> +The initiator sends an ISAKMP/IKE delete to clean up the phase 2 SAs as described in +<a href="#teardown">Renewal and teardown</a>. + +</p> +<p> +Whether or not to delete the phase 1 SAs +at this time is left as a local implementation issue. Implementations +that do delete the phase 1 SAs MUST send authenticated delete messages to +indicate that they are doing so. There is an advantage to keeping +the phase 1 SAs until they expire - they may prove useful again in the +near future. + +</p> +<a name="rfc.section.3.3"></a><h4><a name="anchor26">3.3</a> Keying state machine - responder</h4> + +<p> +The responder has a set of objects identical to those of the initiator. + +</p> +<p> +The responder receives an invitation to create a keying channel from an initiator. + +</p> +<a name="rfc.section.3.3.1"></a><h4><a name="anchor27">3.3.1</a> Unauthenticated OE peer</h4> + +<p> +Upon entering this state, the responder starts a DNS lookup for a KEY record for the +initiator. +The responder looks in the reverse-map for a KEY record for the initiator if the +initiator has offered an ID_IPV4_ADDR, and in the forward map if the +initiator has offered an ID_FQDN type. (See <a href="#RFC2407">[8]</a> section +4.6.2.1.) + +</p> +<p> +The responder exits this state upon successful receipt of a KEY from DNS, and use of the key +to verify the signature of the initiator. + +</p> +<p> +Successful authentication of the peer results in a transition to the +authenticated OE Peer state. + +</p> +<p> +Note that the unauthenticated OE peer state generally occurs in the middle of the key negotiation +protocol. It is really a form of pseudo-state. + +</p> +<a name="rfc.section.3.3.2"></a><h4><a name="anchor28">3.3.2</a> Authenticated OE Peer</h4> + +<p> +The peer will eventually propose one or more phase 2 SAs. The responder uses the source and +destination address in the proposal to +finish instantiating the connection state +using the connection class table. +The responder MUST search for an identical connection object at this point. + +</p> +<p> +If an identical connection is found, then the responder deletes the old instance, +and the new object makes a transition to the pending OE connection state. This means +that new ISAKMP connections with a given peer will always use the latest +instance, which is the correct one if the peer has rebooted in the interim. + +</p> +<p> +If an identical connection is not found, then the responder makes the transition according to the +rules given for the initiator. + +</p> +<p> +Note that if the initiator is in OE-paranoid mode and the responder is in +either always-clear-text or deny, then no communication is possible according +to policy. An implementation is permitted to create new types of policies +such as "accept OE but do not initiate it". This is a local matter. + +</p> +<a name="rfc.section.3.4"></a><h4><a name="teardown">3.4</a> Renewal and teardown</h4> + +<a name="rfc.section.3.4.1"></a><h4><a name="anchor29">3.4.1</a> Aging</h4> + +<p> +A potentially unlimited number of tunnels may exist. In practice, only a few +tunnels are used during a period of time. Unused tunnels MUST, therefore, be +torn down. Detecting when tunnels are no longer in use is the subject of this section. + +</p> +<p> +There are two methods for removing tunnels: explicit deletion or expiry. + +</p> +<p> +Explicit deletion requires an IKE delete message. As the deletes +MUST be authenticated, both ends of the tunnel must maintain the +key channel (phase 1 ISAKMP SA). An implementation which refuses to either maintain or +recreate the keying channel SA will be unable to use this method. + +</p> +<p> +The tunnel expiry method, simply allows the IKE daemon to +expire normally without attempting to re-key it. + +</p> +<p> +Regardless of which method is used to remove tunnels, the implementation requires +a method to determine if the tunnel is still in use. The specifics are a +local matter, but the FreeS/WAN project uses the following criteria. These +criteria are currently implemented in the key management daemon, but could +also be implemented at the SPD layer using an idle timer. + +</p> +<p> +Set a short initial (soft) lifespan of 1 minute since many net flows last +only a few seconds. + +</p> +<p> +At the end of the lifespan, check to see if the tunnel was used by +traffic in either direction during the last 30 seconds. If so, assign a +longer tentative lifespan of 20 minutes after which, look again. If the +tunnel is not in use, then close the tunnel. + +</p> +<p> +The expiring state in the key management +system (see <a href="#expiring">Expiring connection</a>) implements these timeouts. +The timer above may be in the forwarding plane, +but then it must be re-settable. + +</p> +<p> +The tentative lifespan is independent of re-keying; it is just the time when +the tunnel's future is next considered. +(The term lifespan is used here rather than lifetime for this reason.) +Unlike re-keying, this tunnel use check is not costly and should happen +reasonably frequently. + +</p> +<p> +A multi-step back-off algorithm is not considered worth the effort here. + +</p> +<p> +If the security gateway and the client host are the +same and not a Bump-in-the-Stack or Bump-in-the-Wire implementation, tunnel +teardown decisions MAY pay attention to TCP connection status as reported +by the local TCP layer. A still-open TCP connection is almost a guarantee that more traffic is +expected. Closing of the only TCP connection through a tunnel is a +strong hint that no more traffic is expected. + +</p> +<a name="rfc.section.3.4.2"></a><h4><a name="anchor30">3.4.2</a> Teardown and cleanup</h4> + +<p> +Teardown should always be coordinated between the two ends of the tunnel by +interpreting and sending delete notifications. There is a +detailed sub-state in the expired connection state of the key manager that +relates to retransmits of the delete notifications, but this is considered to +be a keying system detail. + +</p> +<p> +On receiving a delete for the outbound SAs of a tunnel (or some subset of +them), tear down the inbound ones also and notify the remote end with a +delete. If the local system receives a delete for a tunnel which is no longer in +existence, then two delete messages have crossed paths. Ignore the delete. +The operation has already been completed. Do not generate any messages in this +situation. + +</p> +<p> +Tunnels are to be considered as bidirectional entities, even though the +low-level protocols don't treat them this way. + +</p> +<p> +When the deletion is initiated locally, rather than as a +response to a received delete, send a delete for (all) the +inbound SAs of a tunnel. If the local system does not receive a responding delete +for the outbound SAs, try re-sending the original +delete. Three tries spaced 10 seconds apart seems a reasonable +level of effort. A failure of the other end to respond after 3 attempts, +indicates that the possibility of further communication is unlikely. Remove the outgoing SAs. +(The remote system may be a mobile node that is no longer present or powered on.) + +</p> +<p> +After re-keying, transmission should switch to using the new +outgoing SAs (ISAKMP or IPsec) immediately, and the old leftover +outgoing SAs should be cleared out promptly (delete should be sent +for the outgoing SAs) rather than waiting for them to expire. This +reduces clutter and minimizes confusion for the operator doing diagnostics. + +</p> +<a name="anchor31"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.4"></a><h3>4. Impacts on IKE</h3> + +<a name="rfc.section.4.1"></a><h4><a name="anchor32">4.1</a> ISAKMP/IKE protocol</h4> + +<p> + The IKE wire protocol needs no modifications. The major changes are + implementation issues relating to how the proposals are interpreted, and from + whom they may come. + +</p> +<p> + As opportunistic encryption is designed to be useful between peers without + prior operator configuration, an IKE daemon must be prepared to negotiate + phase 1 SAs with any node. This may require a large amount of resources to + maintain cookie state, as well as large amounts of entropy for nonces, + cookies and so on. + +</p> +<p> + The major changes to support opportunistic encryption are at the IKE daemon + level. These changes relate to handling of key acquisition requests, lookup + of public keys and TXT records, and interactions with firewalls and other + security facilities that may be co-resident on the same gateway. + +</p> +<a name="rfc.section.4.2"></a><h4><a name="anchor33">4.2</a> Gateway discovery process</h4> + +<p> + In a typical configured tunnel, the address of SG-B is provided + via configuration. Furthermore, the mapping of an SPD entry to a gateway is + typically a 1:1 mapping. When the 0.0.0.0/0 SPD entry technique is used, then + the mapping to a gateway is determined by the reverse DNS records. + +</p> +<p> + The need to do a DNS lookup and wait for a reply will typically introduce a + new state and a new event source (DNS replies) to IKE. Although a +synchronous DNS request can be implemented for proof of concept, experience +is that it can cause very high latencies when a queue of queries must +all timeout in series. + +</p> +<p> + Use of an asynchronous DNS lookup will also permit overlap of DNS lookups with + some of the protocol steps. + +</p> +<a name="rfc.section.4.3"></a><h4><a name="anchor34">4.3</a> Self identification</h4> + +<p> + SG-A will have to establish its identity. Use an + IPv4 ID in phase 1. + +</p> +<p> There are many situations where the administrator of SG-A may not be + able to control the reverse DNS records for SG-A's public IP address. + Typical situations include dialup connections and most residential-type broadband Internet access + (ADSL, cable-modem) connections. In these situations, a fully qualified domain + name that is under the control of SG-A's administrator may be used + when acting as an initiator only. + The FQDN ID should be used in phase 1. See <a href="#fqdn">Use of FQDN IDs</a> + for more details and restrictions. + +</p> +<a name="rfc.section.4.4"></a><h4><a name="anchor35">4.4</a> Public key retrieval process</h4> + +<p> + Upon receipt of a phase 1 SA proposal with either an IPv4 (IPv6) ID or + an FQDN ID, an IKE daemon needs to examine local caches and + configuration files to determine if this is part of a configured tunnel. + If no configured tunnels are found, then the implementation should attempt to retrieve + a KEY record from the reverse DNS in the case of an IPv4/IPv6 ID, or + from the forward DNS in the case of FQDN ID. + +</p> +<p> + It is reasonable that if other non-local sources of policy are used + (COPS, LDAP), they be consulted concurrently but some + clear ordering of policy be provided. Note that due to variances in + latency, implementations must wait for positive or negative replies from all sources + of policy before making any decisions. + +</p> +<a name="rfc.section.4.5"></a><h4><a name="anchor36">4.5</a> Interactions with DNSSEC</h4> + +<p> + The implementation described (1.98) neither uses DNSSEC directly to + explicitly verify the authenticity of zone information, nor uses the NXT + records to provide authentication of the absence of a TXT or KEY + record. Rather, this implementation uses a trusted path to a DNSSEC + capable caching resolver. + +</p> +<p> + To distinguish between an authenticated and an unauthenticated DNS + resource record, a stub resolver capable of returning DNSSEC + information MUST be used. + +</p> +<a name="rfc.section.4.6"></a><h4><a name="anchor37">4.6</a> Required proposal types</h4> + +<a name="rfc.section.4.6.1"></a><h4><a name="phase1id">4.6.1</a> Phase 1 parameters</h4> + +<p> + Main mode MUST be used. + +</p> +<p> + The initiator MUST offer at least one proposal using some combination + of: 3DES, HMAC-MD5 or HMAC-SHA1, DH group 2 or 5. Group 5 SHOULD be + proposed first. + <a href="#RFC3526">[11]</a> +</p> +<p> + The initiator MAY offer additional proposals, but the cipher MUST not + be weaker than 3DES. The initiator SHOULD limit the number of proposals + such that the IKE datagrams do not need to be fragmented. + +</p> +<p> + The responder MUST accept one of the proposals. If any configuration + of the responder is required then the responder is not acting in an + opportunistic way. + +</p> +<p> + SG-A SHOULD use an ID_IPV4_ADDR (ID_IPV6_ADDR for IPv6) of the external + interface of SG-A for phase 1. (There is an exception, see <a href="#fqdn">Use of FQDN IDs</a>.) The authentication method MUST be RSA public key signatures. + The RSA key for SG-A SHOULD be placed into a DNS KEY record in + the reverse space of SG-A (i.e. using in-addr.arpa). + +</p> +<a name="rfc.section.4.6.2"></a><h4><a name="phase2id">4.6.2</a> Phase 2 parameters</h4> + +<p> + SG-A MUST propose a tunnel between Alice and Bob, using 3DES-CBC + mode, MD5 or SHA1 authentication. Perfect Forward Secrecy MUST be specified. + +</p> +<p> + Tunnel mode MUST be used. + +</p> +<p> + Identities MUST be ID_IPV4_ADDR_SUBNET with the mask being /32. + +</p> +<p> + Authorization for SG-A to act on Alice's behalf is determined by + looking for a TXT record in the reverse-map at Alice's address. + +</p> +<p> + Compression SHOULD NOT be mandatory. It may be offered as an option. + +</p> +<a name="anchor38"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.5"></a><h3>5. DNS issues</h3> + +<a name="rfc.section.5.1"></a><h4><a name="KEY">5.1</a> Use of KEY record</h4> + +<p> + In order to establish their own identities, SG-A and SG-B SHOULD publish + their public keys in their reverse DNS via + DNSSEC's KEY record. + See section 3 of <a href="#RFC2535">RFC 2535</a>[16]. + +</p> +<p> +<p>For example: +</p></font><pre> +KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8 +</pre><font face="verdana, helvetica, arial, sans-serif" size="2"> + +<blockquote class="text"><dl> +<dt>0x4200:</dt> +<dd> The flag bits, indicating that this key is prohibited + for confidentiality use (it authenticates the peer only, a separate + Diffie-Hellman exchange is used for + confidentiality), and that this key is associated with the non-zone entity + whose name is the RR owner name. No other flags are set. +</dd> +<dt>4:</dt> +<dd>This indicates that this key is for use by IPsec. +</dd> +<dt>1:</dt> +<dd>An RSA key is present. +</dd> +<dt>AQNJjkKlIk9...nYyUkKK8:</dt> +<dd>The public key of the host as described in <a href="#RFC3110">[17]</a>. +</dd> +</dl></blockquote><p> +</p> +<p>Use of several KEY records allows for key rollover. The SIG Payload in + IKE phase 1 SHOULD be accepted if the public key given by any KEY RR + validates it. + +</p> +<a name="rfc.section.5.2"></a><h4><a name="TXT">5.2</a> Use of TXT delegation record</h4> + +<p> +Alice publishes a TXT record to provide authorization for SG-A to act on +Alice's behalf. + +Bob publishes a TXT record to provide authorization for SG-B to act on Bob's +behalf. + +These records are located in the reverse DNS (in-addr.arpa) for their +respective IP addresses. The reverse DNS SHOULD be secured by DNSSEC, when +it is deployed. DNSSEC is required to defend against active attacks. + +</p> +<p> + If Alice's address is P.Q.R.S, then she can authorize another node to + act on her behalf by publishing records at: + </p> +</font><pre> +S.R.Q.P.in-addr.arpa + </pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> + +</p> +<p> + The contents of the resource record are expected to be a string that + uses the following syntax, as suggested in <a href="#RFC1464">[15]</a>. + (Note that the reply to query may include other TXT resource + records used by other applications.) + + <br><hr size="1" shade="0"> +<a name="txtformat"></a> +</p> +</font><pre> +X-IPsec-Server(P)=A.B.C.D KEY + </pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Format of reverse delegation record </b></font><br></td></tr></table><hr size="1" shade="0"> + +</p> +<blockquote class="text"><dl> +<dt>P:</dt> +<dd> Specifies a precedence for this record. This is + similar to MX record preferences. Lower numbers have stronger + preference. + +</dd> +<dt>A.B.C.D:</dt> +<dd> Specifies the IP address of the Security Gateway + for this client machine. + +</dd> +<dt>KEY:</dt> +<dd> Is the encoded RSA Public key of the Security + Gateway. The key is provided here to avoid a second DNS lookup. If this + field is absent, then a KEY resource record should be looked up in the + reverse-map of A.B.C.D. The key is transmitted in base64 format. + +</dd> +</dl></blockquote><p> +<p> + The pieces of the record are separated by any whitespace + (space, tab, newline, carriage return). An ASCII space SHOULD + be used. + +</p> +<p> + In the case where Alice is located at a public address behind a + security gateway that has no fixed address (or no control over its + reverse-map), then Alice may delegate to a public key by domain name. + + <br><hr size="1" shade="0"> +<a name="txtfqdnformat"></a> +</p> +</font><pre> +X-IPsec-Server(P)=@FQDN KEY + </pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Format of reverse delegation record (FQDN version) </b></font><br></td></tr></table><hr size="1" shade="0"> + +</p> +<blockquote class="text"><dl> +<dt>P:</dt> +<dd> Is as above. + +</dd> +<dt>FQDN:</dt> +<dd> Specifies the FQDN that the Security Gateway + will identify itself with. + +</dd> +<dt>KEY:</dt> +<dd> Is the encoded RSA Public key of the Security + Gateway. +</dd> +</dl></blockquote><p> +<p> + If there is more than one such TXT record with strongest (lowest + numbered) precedence, one Security Gateway is picked arbitrarily from + those specified in the strongest-preference records. + +</p> +<a name="rfc.section.5.2.1"></a><h4><a name="anchor39">5.2.1</a> Long TXT records</h4> + +<p> + When packed into transport format, TXT records which are longer than 255 + characters are divided into smaller <character-strings>. + (See <a href="#RFC1035">[13]</a> section 3.3 and 3.3.14.) These MUST + be reassembled into a single string for processing. + Whitespace characters in the base64 encoding are to be ignored. + +</p> +<a name="rfc.section.5.2.2"></a><h4><a name="anchor40">5.2.2</a> Choice of TXT record</h4> + +<p> + It has been suggested to use the KEY, OPT, CERT, or KX records + instead of a TXT record. None is satisfactory. + +</p> +<p> The KEY RR has a protocol field which could be used to indicate a new protocol, +and an algorithm field which could be used to + indicate different contents in the key data. However, the KEY record + is clearly not intended for storing what are really authorizations, + it is just for identities. Other uses have been discouraged. + +</p> +<p> OPT resource records, as defined in <a href="#RFC2671">[14]</a> are not + intended to be used for storage of information. They are not to be loaded, + cached or forwarded. They are, therefore, inappropriate for use here. + +</p> +<p> + CERT records <a href="#RFC2538">[18]</a> can encode almost any set of + information. A custom type code could be used permitting any suitable + encoding to be stored, not just X.509. According to + the RFC, the certificate RRs are to be signed internally which may add undesirable +and unnecessary bulk. Larger DNS records may require TCP instead of UDP transfers. + +</p> +<p> + At the time of protocol design, the CERT RR was not widely deployed and + could not be counted upon. Use of CERT records will be investigated, + and may be proposed in a future revision of this document. + +</p> +<p> + KX records are ideally suited for use instead of TXT records, but had not been deployed at + the time of implementation. + +</p> +<a name="rfc.section.5.3"></a><h4><a name="fqdn">5.3</a> Use of FQDN IDs</h4> + +<p> + Unfortunately, not every administrator has control over the contents + of the reverse-map. Where the initiator (SG-A) has no suitable reverse-map, the + authorization record present in the reverse-map of Alice may refer to a + FQDN instead of an IP address. + +</p> +<p> + In this case, the client's TXT record gives the fully qualified domain + name (FQDN) in place of its security gateway's IP address. + The initiator should use the ID_FQDN ID-payload in phase 1. + A forward lookup for a KEY record on the FQDN must yield the + initiator's public key. + +</p> +<p> + This method can also be used when the external address of SG-A is + dynamic. + +</p> +<p> + If SG-A is acting on behalf of Alice, then Alice must still delegate + authority for SG-A to do so in her reverse-map. When Alice and SG-A + are one and the same (i.e. Alice is acting as an end-node) then there + is no need for this when initiating only. +</p> +<p>However, Alice must still delegate to herself if she wishes others to + initiate OE to her. See <a href="#txtfqdnformat">Format of reverse delegation record (FQDN version)</a>. + +</p> +<a name="rfc.section.5.4"></a><h4><a name="anchor41">5.4</a> Key roll-over</h4> + +<p> +Good cryptographic hygiene says that one should replace public/private key pairs +periodically. Some administrators may wish to do this as often as daily. Typical DNS +propagation delays are determined by the SOA Resource Record MINIMUM +parameter, which controls how long DNS replies may be cached. For reasonable +operation of DNS servers, administrators usually want this value to be at least several +hours, sometimes as a long as a day. This presents a problem - a new key MUST +not be used prior to it propagating through DNS. + +</p> +<p> +This problem is dealt with by having the Security Gateway generate a new +public/private key pair at least MINIMUM seconds in advance of using it. It +then adds this key to the DNS (both as a second KEY record and in additional TXT +delegation records) at key generation time. Note: only one key is allowed in +each TXT record. + +</p> +<p> +When authenticating, all gateways MUST have available all public keys +that are found in DNS for this entity. This permits the authenticating end +to check both the key for "today" and the key for "tomorrow". Note that it is +the end which is creating the signature (possesses the private key) that +determines which key is to be used. + +</p> +<a name="anchor42"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.6"></a><h3>6. Network address translation interaction</h3> + +<p> + There are no fundamentally new issues for implementing opportunistic encryption + in the presence of network address translation. Rather there are + only the regular IPsec issues with NAT traversal. + +</p> +<p> + There are several situations to consider for NAT. + +</p> +<a name="rfc.section.6.1"></a><h4><a name="anchor43">6.1</a> Co-located NAT/NAPT</h4> + +<p> + If SG-A is also performing network address translation on + behalf of Alice, then the packet should be translated prior to + being subjected to opportunistic encryption. This is in contrast to + typically configured tunnels which often exist to bridge islands of + private network address space. SG-A will use the translated source + address for phase 2, and so SG-B will look up that address to + confirm SG-A's authorization. + +</p> +<p> In the case of NAT (1:1), the address space into which the + translation is done MUST be globally unique, and control over the + reverse-map is assumed. + Placing of TXT records is possible. + +</p> +<p> In the case of NAPT (m:1), the address will be SG-A. The ability to get + KEY and TXT records in place will again depend upon whether or not + there is administrative control over the reverse-map. This is + identical to situations involving a single host acting on behalf of + itself. + + FQDN style can be used to get around a lack of a reverse-map for + initiators only. + +</p> +<a name="rfc.section.6.2"></a><h4><a name="anchor44">6.2</a> SG-A behind NAT/NAPT</h4> + +<p> + If there is a NAT or NAPT between SG-A and SG-B, then normal IPsec + NAT traversal rules apply. In addition to the transport problem + which may be solved by other mechanisms, there + is the issue of what phase 1 and phase 2 IDs to use. While FQDN could + be used during phase 1 for SG-A, there is no appropriate ID for phase 2 + that permits SG-B to determine that SG-A is in fact authorized to speak for Alice. + +</p> +<a name="rfc.section.6.3"></a><h4><a name="anchor45">6.3</a> Bob is behind a NAT/NAPT</h4> + +<p> + If Bob is behind a NAT (perhaps SG-B), then there is, in fact, no way for + Alice to address a packet to Bob. Not only is opportunistic encryption + impossible, but it is also impossible for Alice to initiate any + communication to Bob. It may be possible for Bob to initiate in such + a situation. This creates an asymmetry, but this is common for + NAPT. + +</p> +<a name="anchor46"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.7"></a><h3>7. Host implementations</h3> + +<p> + When Alice and SG-A are components of the same system, they are + considered to be a host implementation. The packet sequence scenario remains unchanged. + +</p> +<p> + Components marked Alice are the upper layers (TCP, UDP, the + application), and SG-A is the IP layer. + +</p> +<p> + Note that tunnel mode is still required. + +</p> +<p> + As Alice and SG-A are acting on behalf of themselves, no TXT based delegation + record is necessary for Alice to initiate. She can rely on FQDN in a + forward map. This is particularly attractive to mobile nodes such as + notebook computers at conferences. + To respond, Alice/SG-A will still need an entry in Alice's reverse-map. + +</p> +<a name="anchor47"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.8"></a><h3>8. Multi-homing</h3> + +<p> +If there are multiple paths between Alice and Bob (as illustrated in +the diagram with SG-D), then additional DNS records are required to establish +authorization. + +</p> +<p> +In <a href="#networkdiagram">Reference Network Diagram</a>, Alice has two ways to +exit her network: SG-A and SG-D. Previously SG-D has been ignored. Postulate +that there are routers between Alice and her set of security gateways +(denoted by the + signs and the marking of an autonomous system number for +Alice's network). Datagrams may, therefore, travel to either SG-A or SG-D en +route to Bob. + +</p> +<p> +As long as all network connections are in good order, it does not matter how +datagrams exit Alice's network. When they reach either security gateway, the +security gateway will find the TXT delegation record in Bob's reverse-map, +and establish an SA with SG-B. + +</p> +<p> +SG-B has no problem establishing that either of SG-A or SG-D may speak for +Alice, because Alice has published two equally weighted TXT delegation records: + <br><hr size="1" shade="0"> +<a name="txtmultiexample"></a> +</p> +</font><pre> +X-IPsec-Server(10)=192.1.1.5 AQMM...3s1Q== +X-IPsec-Server(10)=192.1.1.6 AAJN...j8r9== + </pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Multiple gateway delegation example for Alice </b></font><br></td></tr></table><hr size="1" shade="0"> + +</p> +<p> +Alice's routers can now do any kind of load sharing needed. Both SG-A and SG-D send datagrams addressed to Bob through +their tunnel to SG-B. + +</p> +<p> +Alice's use of non-equal weight delegation records to show preference of one gateway over another, has relevance only when SG-B +is initiating to Alice. + +</p> +<p> +If the precedences are the same, then SG-B has a more difficult time. It +must decide which of the two tunnels to use. SG-B has no information about +which link is less loaded, nor which security gateway has more cryptographic +resources available. SG-B, in fact, has no knowledge of whether both gateways +are even reachable. + +</p> +<p> +The Public Internet's default-free zone may well know a good route to Alice, +but the datagrams that SG-B creates must be addressed to either SG-A or SG-D; +they can not be addressed to Alice directly. + +</p> +<p> +SG-B may make a number of choices: + +<ol class="text"> +<li>It can ignore the problem and round robin among the tunnels. This + causes losses during times when one or the other security gateway is + unreachable. If this worries Alice, she can change the weights in her + TXT delegation records. +</li> +<li>It can send to the gateway from which it most recently received datagrams. + This assumes that routing and reachability are symmetrical. +</li> +<li>It can listen to BGP information from the Internet to decide which + system is currently up. This is clearly much more complicated, but if SG-B is already participating + in the BGP peering system to announce Bob, the results data may already + be available to it. +</li> +<li>It can refuse to negotiate the second tunnel. (It is unclear whether or +not this is even an option.) +</li> +<li>It can silently replace the outgoing portion of the first tunnel with the +second one while still retaining the incoming portions of both. SG-B can, +thus, accept datagrams from either SG-A or SG-D, but +send only to the gateway that most recently re-keyed with it. +</li> +</ol><p> +</p> +<p> +Local policy determines which choice SG-B makes. Note that even if SG-B has perfect +knowledge about the reachability of SG-A and SG-D, Alice may not be reachable +from either of these security gateways because of internal reachability +issues. + +</p> +<p> +FreeS/WAN implements option 5. Implementing a different option is +being considered. The multi-homing aspects of OE are not well developed and may +be the subject of a future document. + +</p> +<a name="anchor48"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.9"></a><h3>9. Failure modes</h3> + +<a name="rfc.section.9.1"></a><h4><a name="anchor49">9.1</a> DNS failures</h4> + +<p> + If a DNS server fails to respond, local policy decides + whether or not to permit communication in the clear as embodied in + the connection classes in <a href="#initclasses">Keying state machine - initiator</a>. + It is easy to mount a denial of service attack on the DNS server + responsible for a particular network's reverse-map. + Such an attack may cause all communication with that network to go in + the clear if the policy is permissive, or fail completely + if the policy is paranoid. Please note that this is an active attack. + +</p> +<p> + There are still many networks + that do not have properly configured reverse-maps. Further, if the policy is not to communicate, + the above denial of service attack isolates the target network. Therefore, the decision of whether +or not to permit communication in the clear MUST be a matter of local policy. + +</p> +<a name="rfc.section.9.2"></a><h4><a name="anchor50">9.2</a> DNS configured, IKE failures</h4> + +<p> + DNS records claim that opportunistic encryption should + occur, but the target gateway either does not respond on port 500, or + refuses the proposal. This may be because of a crash or reboot, a + faulty configuration, or a firewall filtering port 500. + +</p> +<p> + The receipt of ICMP port, host or network unreachable + messages indicates a potential problem, but MUST NOT cause communication + to fail + immediately. ICMP messages are easily forged by attackers. If such a + forgery caused immediate failure, then an active attacker could easily + prevent any + encryption from ever occurring, possibly preventing all communication. + +</p> +<p> + In these situations a clear log should be produced + and local policy should dictate if communication is then + permitted in the clear. + +</p> +<a name="rfc.section.9.3"></a><h4><a name="anchor51">9.3</a> System reboots</h4> + +<p> +Tunnels sometimes go down because the remote end crashes, +disconnects, or has a network link break. In general there is no +notification of this. Even in the event of a crash and successful reboot, +other SGs don't hear about it unless the rebooted SG has specific +reason to talk to them immediately. Over-quick response to temporary +network outages is undesirable. Note that a tunnel can be torn +down and then re-established without any effect visible to the user +except a pause in traffic. On the other hand, if one end reboots, +the other end can't get datagrams to it at all (except via +IKE) until the situation is noticed. So a bias toward quick +response is appropriate even at the cost of occasional +false alarms. + +</p> +<p> +A mechanism for recovery after reboot is a topic of current research and is not specified in this +document. + +</p> +<p> +A deliberate shutdown should include an attempt, using deletes, to notify all other SGs +currently connected by phase 1 SAs that communication is +about to fail. Again, a remote SG will assume this is a teardown. Attempts by the +remote SGs to negotiate new tunnels as replacements should be ignored. When possible, +SGs should attempt to preserve information about currently-connected SGs in non-volatile storage, so +that after a crash, an Initial-Contact can be sent to previous partners to +indicate loss of all previously established connections. + +</p> +<a name="anchor52"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.10"></a><h3>10. Unresolved issues</h3> + +<a name="rfc.section.10.1"></a><h4><a name="anchor53">10.1</a> Control of reverse DNS</h4> + +<p> + The method of obtaining information by reverse DNS lookup causes + problems for people who cannot control their reverse DNS + bindings. This is an unresolved problem in this version, and is out + of scope. + +</p> +<a name="anchor54"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.11"></a><h3>11. Examples</h3> + +<a name="rfc.section.11.1"></a><h4><a name="anchor55">11.1</a> Clear-text usage (permit policy)</h4> + +<p> +Two example scenarios follow. In the first example GW-A +(Gateway A) and GW-B (Gateway B) have always-clear-text policies, and in the second example they have an OE +policy. + +</p><br><hr size="1" shade="0"> +<a name="regulartiming"></a> +</font><pre> + Alice SG-A DNS SG-B Bob + (1) + ------(2)--------------> + <-----(3)--------------- + (4)----(5)-----> + ----------(6)------> + ------(7)-----> + <------(8)------ + <----------(9)------ + <----(10)----- + (11)-----------> + ----------(12)-----> + --------------> + <--------------- + <------------------- + <------------- + </pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Timing of regular transaction </b></font><br></td></tr></table><hr size="1" shade="0"> + +<p> +Alice wants to communicate with Bob. Perhaps she wants to retrieve a +web page from Bob's web server. In the absence of opportunistic +encryptors, the following events occur: + +<blockquote class="text"><dl> +<dt>(1)</dt> +<dd>Human or application 'clicks' with a name. +</dd> +<dt>(2)</dt> +<dd>Application looks up name in DNS to get IP address. +</dd> +<dt>(3)</dt> +<dd>Resolver returns A record to application. +</dd> +<dt>(4)</dt> +<dd>Application starts a TCP session or UDP session and OS sends datagram. +</dd> +<dt>(5)</dt> +<dd>Datagram is seen at first gateway from Alice (SG-A). (SG-A +makes a transition through Empty connection to always-clear connection and +instantiates a pass-through policy at the forwarding plane.) +</dd> +<dt>(6)</dt> +<dd>Datagram is seen at last gateway before Bob (SG-B). +</dd> +<dt>(7)</dt> +<dd>First datagram from Alice is seen by Bob. +</dd> +<dt>(8)</dt> +<dd>First return datagram is sent by Bob. +</dd> +<dt>(9)</dt> +<dd>Datagram is seen at Bob's gateway. (SG-B makes a transition through +Empty connection to always-clear connection and instantiates a pass-through +policy at the forwarding plane.) +</dd> +<dt>(10)</dt> +<dd>Datagram is seen at Alice's gateway. +</dd> +<dt>(11)</dt> +<dd>OS hands datagram to application. Alice sends another datagram. +</dd> +<dt>(12)</dt> +<dd>A second datagram traverses the Internet. +</dd> +</dl></blockquote><p> +</p> +<a name="rfc.section.11.2"></a><h4><a name="anchor56">11.2</a> Opportunistic encryption</h4> + +<p> +In the presence of properly configured opportunistic encryptors, the +event list is extended. + +<br><hr size="1" shade="0"> +<a name="opportunistictiming"></a> +</p> +</font><pre> + Alice SG-A DNS SG-B Bob + (1) + ------(2)--------------> + <-----(3)--------------- + (4)----(5)----->+ + ----(5B)-> + <---(5C)-- + ~~~~~~~~~~~~~(5D)~~~> + <~~~~~~~~~~~~(5E1)~~~ + ~~~~~~~~~~~~~(5E2)~~> + <~~~~~~~~~~~~(5E3)~~~ + #############(5E4)##> + <############(5E5)### + <----(5F1)-- + -----(5F2)-> + #############(5G1)##> + <----(5H1)-- + -----(5H2)-> + <############(5G2)### + #############(5G3)##> + ============(6)====> + ------(7)-----> + <------(8)------ + <==========(9)====== + <-----(10)---- + (11)-----------> + ==========(12)=====> + --------------> + <--------------- + <=================== + <------------- + </pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Timing of opportunistic encryption transaction </b></font><br></td></tr></table><hr size="1" shade="0"> + +<blockquote class="text"><dl> +<dt>(1)</dt> +<dd>Human or application clicks with a name. +</dd> +<dt>(2)</dt> +<dd>Application initiates DNS mapping. +</dd> +<dt>(3)</dt> +<dd>Resolver returns A record to application. +</dd> +<dt>(4)</dt> +<dd>Application starts a TCP session or UDP. +</dd> +<dt>(5)</dt> +<dd>SG-A (host or SG) sees datagram to target, and buffers it. +</dd> +<dt>(5B)</dt> +<dd>SG-A asks DNS for TXT record. +</dd> +<dt>(5C)</dt> +<dd>DNS returns TXT record(s). +</dd> +<dt>(5D)</dt> +<dd>Initial IKE Main Mode Packet goes out. +</dd> +<dt>(5E)</dt> +<dd>IKE ISAKMP phase 1 succeeds. +</dd> +<dt>(5F)</dt> +<dd>SG-B asks DNS for TXT record to prove SG-A is an agent for Alice. +</dd> +<dt>(5G)</dt> +<dd>IKE phase 2 negotiation. +</dd> +<dt>(5H)</dt> +<dd>DNS lookup by responder (SG-B). +</dd> +<dt>(6)</dt> +<dd>Buffered datagram is sent by SG-A. +</dd> +<dt>(7)</dt> +<dd>Datagram is received by SG-B, decrypted, and sent to Bob. +</dd> +<dt>(8)</dt> +<dd>Bob replies, and datagram is seen by SG-B. +</dd> +<dt>(9)</dt> +<dd>SG-B already has tunnel up with SG-A, and uses it. +</dd> +<dt>(10)</dt> +<dd>SG-A decrypts datagram and gives it to Alice. +</dd> +<dt>(11)</dt> +<dd>Alice receives datagram. Sends new packet to Bob. +</dd> +<dt>(12)</dt> +<dd>SG-A gets second datagram, sees that tunnel is up, and uses it. +</dd> +</dl></blockquote><p> +</p> +<p> + For the purposes of this section, we will describe only the changes that + occur between <a href="#regulartiming">Timing of regular transaction</a> and + <a href="#opportunistictiming">Timing of opportunistic encryption transaction</a>. This corresponds to time points 5, 6, 7, 9 and 10 on the list above. + +</p> +<a name="rfc.section.11.2.1"></a><h4><a name="anchor57">11.2.1</a> (5) IPsec datagram interception</h4> + +<p> + At point (5), SG-A intercepts the datagram because this source/destination pair lacks a policy +(the non-existent policy state). SG-A creates a hold policy, and buffers the datagram. SG-A requests keys from the keying daemon. + +</p> +<a name="rfc.section.11.2.2"></a><h4><a name="anchor58">11.2.2</a> (5B) DNS lookup for TXT record</h4> + +<p> + SG-A's IKE daemon, having looked up the source/destination pair in the connection + class list, creates a new Potential OE connection instance. SG-A starts DNS + queries. + +</p> +<a name="rfc.section.11.2.3"></a><h4><a name="anchor59">11.2.3</a> (5C) DNS returns TXT record(s)</h4> + +<p> + DNS returns properly formed TXT delegation records, and SG-A's IKE daemon + causes this instance to make a transition from Potential OE connection to Pending OE + connection. + +</p> +<p> + Using the example above, the returned record might contain: + + <br><hr size="1" shade="0"> +<a name="txtexample"></a> +</p> +</font><pre> +X-IPsec-Server(10)=192.1.1.5 AQMM...3s1Q== + </pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Example of reverse delegation record for Bob </b></font><br></td></tr></table><hr size="1" shade="0"> + + with SG-B's IP address and public key listed. + +</p> +<a name="rfc.section.11.2.4"></a><h4><a name="anchor60">11.2.4</a> (5D) Initial IKE main mode packet goes out</h4> + +<p>Upon entering Pending OE connection, SG-A sends the initial ISAKMP + message with proposals. See <a href="#phase1id">Phase 1 parameters</a>. + +</p> +<a name="rfc.section.11.2.5"></a><h4><a name="anchor61">11.2.5</a> (5E1) Message 2 of phase 1 exchange</h4> + +<p> + SG-B receives the message. A new connection instance is created in the + unauthenticated OE peer state. + +</p> +<a name="rfc.section.11.2.6"></a><h4><a name="anchor62">11.2.6</a> (5E2) Message 3 of phase 1 exchange</h4> + +<p> + SG-A sends a Diffie-Hellman exponent. This is an internal state of the + keying daemon. + +</p> +<a name="rfc.section.11.2.7"></a><h4><a name="anchor63">11.2.7</a> (5E3) Message 4 of phase 1 exchange</h4> + +<p> + SG-B responds with a Diffie-Hellman exponent. This is an internal state of the + keying protocol. + +</p> +<a name="rfc.section.11.2.8"></a><h4><a name="anchor64">11.2.8</a> (5E4) Message 5 of phase 1 exchange</h4> + +<p> + SG-A uses the phase 1 SA to send its identity under encryption. + The choice of identity is discussed in <a href="#phase1id">Phase 1 parameters</a>. + This is an internal state of the keying protocol. + +</p> +<a name="rfc.section.11.2.9"></a><h4><a name="anchor65">11.2.9</a> (5F1) Responder lookup of initiator key</h4> + +<p> + SG-B asks DNS for the public key of the initiator. + DNS looks for a KEY record by IP address in the reverse-map. + That is, a KEY resource record is queried for 4.1.1.192.in-addr.arpa + (recall that SG-A's external address is 192.1.1.4). + SG-B uses the resulting public key to authenticate the initiator. See <a href="#KEY">Use of KEY record</a> for further details. + +</p> +<a name="rfc.section.11.2.10"></a><h4><a name="anchor66">11.2.10</a> (5F2) DNS replies with public key of initiator</h4> + +<p> +Upon successfully authenticating the peer, the connection instance makes a +transition to authenticated OE peer on SG-B. + +</p> +<p> +The format of the TXT record returned is described in +<a href="#TXT">Use of TXT delegation record</a>. + +</p> +<a name="rfc.section.11.2.11"></a><h4><a name="anchor67">11.2.11</a> (5E5) Responder replies with ID and authentication</h4> + +<p> + SG-B sends its ID along with authentication material. This is an internal + state for the keying protocol. + +</p> +<a name="rfc.section.11.2.12"></a><h4><a name="anchor68">11.2.12</a> (5G) IKE phase 2</h4> + +<a name="rfc.section.11.2.12.1"></a><h4><a name="anchor69">11.2.12.1</a> (5G1) Initiator proposes tunnel</h4> + +<p> + Having established mutually agreeable authentications (via KEY) and + authorizations (via TXT), SG-A proposes to create an IPsec tunnel for + datagrams transiting from Alice to Bob. This tunnel is established only for + the Alice/Bob combination, not for any subnets that may be behind SG-A and SG-B. + +</p> +<a name="rfc.section.11.2.12.2"></a><h4><a name="anchor70">11.2.12.2</a> (5H1) Responder determines initiator's authority</h4> + +<p> + While the identity of SG-A has been established, its authority to + speak for Alice has not yet been confirmed. SG-B does a reverse + lookup on Alice's address for a TXT record. + +</p> +<p>Upon receiving this specific proposal, SG-B's connection instance + makes a transition into the potential OE connection state. SG-B may already have an + instance, and the check is made as described above. +</p> +<a name="rfc.section.11.2.12.3"></a><h4><a name="anchor71">11.2.12.3</a> (5H2) DNS replies with TXT record(s)</h4> + +<p> + The returned key and IP address should match that of SG-A. + +</p> +<a name="rfc.section.11.2.12.4"></a><h4><a name="anchor72">11.2.12.4</a> (5G2) Responder agrees to proposal</h4> + +<p> + Should additional communication occur between, for instance, Dave and Bob using + SG-A and SG-B, a new tunnel (phase 2 SA) would be established. The phase 1 SA + may be reusable. + +</p> +<p>SG-A, having successfully keyed the tunnel, now makes a transition from + Pending OE connection to Keyed OE connection. + +</p> +<p>The responder MUST setup the inbound IPsec SAs before sending its reply. +</p> +<a name="rfc.section.11.2.12.5"></a><h4><a name="anchor73">11.2.12.5</a> (5G3) Final acknowledgment from initiator</h4> + +<p> + The initiator agrees with the responder's choice and sets up the tunnel. + The initiator sets up the inbound and outbound IPsec SAs. + +</p> +<p> + The proper authorization returned with keys prompts SG-B to make a transition + to the keyed OE connection state. + +</p> +<p>Upon receipt of this message, the responder may now setup the outbound + IPsec SAs. +</p> +<a name="rfc.section.11.2.13"></a><h4><a name="anchor74">11.2.13</a> (6) IPsec succeeds, and sets up tunnel for communication between Alice and Bob</h4> + +<p> + SG-A sends the datagram saved at step (5) through the newly created + tunnel to SG-B, where it gets decrypted and forwarded. + Bob receives it at (7) and replies at (8). + +</p> +<a name="rfc.section.11.2.14"></a><h4><a name="anchor75">11.2.14</a> (9) SG-B already has tunnel up with G1 and uses it</h4> + +<p> + At (9), SG-B has already established an SPD entry mapping Bob->Alice via a + tunnel, so this tunnel is simply applied. The datagram is encrypted to SG-A, + decrypted by SG-A and passed to Alice at (10). + +</p> +<a name="securityconsiderations"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.12"></a><h3>12. Security considerations</h3> + +<a name="rfc.section.12.1"></a><h4><a name="anchor76">12.1</a> Configured vs opportunistic tunnels</h4> + +<p> + Configured tunnels are those which are setup using bilateral mechanisms: exchanging +public keys (raw RSA, DSA, PKIX), pre-shared secrets, or by referencing keys that +are in known places (distinguished name from LDAP, DNS). These keys are then used to +configure a specific tunnel. + +</p> +<p> +A pre-configured tunnel may be on all the time, or may be keyed only when needed. +The end points of the tunnel are not necessarily static: many mobile +applications (road warrior) are considered to be configured tunnels. + +</p> +<p> +The primary characteristic is that configured tunnels are assigned specific +security properties. They may be trusted in different ways relating to exceptions to +firewall rules, exceptions to NAT processing, and to bandwidth or other quality of service restrictions. + +</p> +<p> +Opportunistic tunnels are not inherently trusted in any strong way. They are +created without prior arrangement. As the two parties are strangers, there +MUST be no confusion of datagrams that arrive from opportunistic peers and +those that arrive from configured tunnels. A security gateway MUST take care +that an opportunistic peer can not impersonate a configured peer. + +</p> +<p> +Ingress filtering MUST be used to make sure that only datagrams authorized by +negotiation (and the concomitant authentication and authorization) are +accepted from a tunnel. This is to prevent one peer from impersonating another. + +</p> +<p> +An implementation suggestion is to treat opportunistic tunnel +datagrams as if they arrive on a logical interface distinct from other +configured tunnels. As the number of opportunistic tunnels that may be +created automatically on a system is potentially very high, careful attention +to scaling should be taken into account. + +</p> +<p> +As with any IKE negotiation, opportunistic encryption cannot be secure +without authentication. Opportunistic encryption relies on DNS for its +authentication information and, therefore, cannot be fully secure without +a secure DNS. Without secure DNS, opportunistic encryption can protect against passive +eavesdropping but not against active man-in-the-middle attacks. + +</p> +<a name="rfc.section.12.2"></a><h4><a name="anchor77">12.2</a> Firewalls versus Opportunistic Tunnels</h4> + +<p> + Typical usage of per datagram access control lists is to implement various +kinds of security gateways. These are typically called "firewalls". + +</p> +<p> + Typical usage of a virtual private network (VPN) within a firewall is to +bypass all or part of the access controls between two networks. Additional +trust (as outlined in the previous section) is given to datagrams that arrive +in the VPN. + +</p> +<p> + Datagrams that arrive via opportunistically configured tunnels MUST not be +trusted. Any security policy that would apply to a datagram arriving in the +clear SHOULD also be applied to datagrams arriving opportunistically. + +</p> +<a name="rfc.section.12.3"></a><h4><a name="anchor78">12.3</a> Denial of service</h4> + +<p> + There are several different forms of denial of service that an implementor + should concern themselves with. Most of these problems are shared with + security gateways that have large numbers of mobile peers (road warriors). + +</p> +<p> + The design of ISAKMP/IKE, and its use of cookies, defend against many kinds + of denial of service. Opportunism changes the assumption that if the phase 1 (ISAKMP) + SA is authenticated, that it was worthwhile creating. Because the gateway will communicate with any machine, it is + possible to form phase 1 SAs with any machine on the Internet. + +</p> +<a name="anchor79"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.13"></a><h3>13. IANA Considerations</h3> + +<p> + There are no known numbers which IANA will need to manage. + +</p> +<a name="anchor80"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.14"></a><h3>14. Acknowledgments</h3> + +<p> + Substantive portions of this document are based upon previous work by + Henry Spencer. + +</p> +<p> + Thanks to Tero Kivinen, Sandy Harris, Wes Hardarker, Robert Moskowitz, + Jakob Schlyter, Bill Sommerfeld, John Gilmore and John Denker for their + comments and constructive criticism. + +</p> +<p> + Sandra Hoffman and Bill Dickie did the detailed proof reading and editing. + +</p> +<a name="rfc.references1"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Normative references</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><b><a name="OEspec">[1]</a></b></td> +<td class="author-text"><a href="mailto:hugh@mimosa.com">Redelmeier, D.</a> and <a href="mailto:henry@spsystems.net">H. Spencer</a>, "Opportunistic Encryption", paper http://www.freeswan.org/freeswan_trees/freeswan-1.91/doc/opportunism.spec, May 2001.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC0791">[2]</a></b></td> +<td class="author-text">Defense Advanced Research Projects Agency (DARPA), Information Processing Techniques Office and University of Southern California (USC)/Information Sciences Institute, "<a href="ftp://ftp.isi.edu/in-notes/rfc791.txt">Internet Protocol</a>", STD 5, RFC 791, September 1981.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC1009">[3]</a></b></td> +<td class="author-text"><a href="mailto:">Braden, R.</a> and <a href="mailto:">J. Postel</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc1009.txt">Requirements for Internet gateways</a>", RFC 1009, June 1987.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC1984">[4]</a></b></td> +<td class="author-text">IAB, IESG, <a href="mailto:brian@dxcoms.cern.ch">Carpenter, B.</a> and <a href="mailto:fred@cisco.com">F. Baker</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc1984.txt">IAB and IESG Statement on Cryptographic Technology and the Internet</a>", RFC 1984, August 1996.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2119">[5]</a></b></td> +<td class="author-text"><a href="mailto:-">Bradner, S.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a>", BCP 14, RFC 2119, March 1997.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2367">[6]</a></b></td> +<td class="author-text"><a href="mailto:danmcd@eng.sun.com">McDonald, D.</a>, <a href="mailto:cmetz@inner.net">Metz, C.</a> and <a href="mailto:phan@itd.nrl.navy.mil">B. Phan</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2367.txt">PF_KEY Key Management API, Version 2</a>", RFC 2367, July 1998.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2401">[7]</a></b></td> +<td class="author-text"><a href="mailto:kent@bbn.com">Kent, S.</a> and <a href="mailto:rja@corp.home.net">R. Atkinson</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2401.txt">Security Architecture for the Internet Protocol</a>", RFC 2401, November 1998.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2407">[8]</a></b></td> +<td class="author-text"><a href="mailto:ddp@network-alchemy.com">Piper, D.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2407.txt">The Internet IP Security Domain of Interpretation for ISAKMP</a>", RFC 2407, November 1998.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2408">[9]</a></b></td> +<td class="author-text"><a href="mailto:wdm@tycho.ncsc.mil">Maughan, D.</a>, <a href="mailto:mss@tycho.ncsc.mil">Schneider, M.</a> and <a href="er@raba.com">M. Schertler</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2408.txt">Internet Security Association and Key Management Protocol (ISAKMP)</a>", RFC 2408, November 1998.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2409">[10]</a></b></td> +<td class="author-text"><a href="mailto:dharkins@cisco.com">Harkins, D.</a> and <a href="mailto:carrel@ipsec.org">D. Carrel</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2409.txt">The Internet Key Exchange (IKE)</a>", RFC 2409, November 1998.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC3526">[11]</a></b></td> +<td class="author-text"><a href="mailto:kivinen@ssh.fi">Kivinen, T.</a> and <a href="mailto:mrskojo@cc.helsinki.fi">M. Kojo</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc3526.txt">More MODP Diffie-Hellman groups for IKE</a>", RFC 3526, March 2003.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC1034">[12]</a></b></td> +<td class="author-text">Mockapetris, P., "<a href="ftp://ftp.isi.edu/in-notes/rfc1034.txt">Domain names - concepts and facilities</a>", STD 13, RFC 1034, November 1987.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC1035">[13]</a></b></td> +<td class="author-text"><a href="mailto:">Mockapetris, P.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc1035.txt">Domain names - implementation and specification</a>", STD 13, RFC 1035, November 1987.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2671">[14]</a></b></td> +<td class="author-text"><a href="mailto:vixie@isc.org">Vixie, P.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2671.txt">Extension Mechanisms for DNS (EDNS0)</a>", RFC 2671, August 1999.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC1464">[15]</a></b></td> +<td class="author-text"><a href="mailto:rosenbaum@lkg.dec.com">Rosenbaum, R.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc1464.txt">Using the Domain Name System To Store Arbitrary String Attributes</a>", RFC 1464, May 1993.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2535">[16]</a></b></td> +<td class="author-text"><a href="mailto:dee3@us.ibm.com">Eastlake, D.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2535.txt">Domain Name System Security Extensions</a>", RFC 2535, March 1999.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC3110">[17]</a></b></td> +<td class="author-text">Eastlake, D., "<a href="ftp://ftp.isi.edu/in-notes/rfc3110.txt">RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)</a>", RFC 3110, May 2001.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2538">[18]</a></b></td> +<td class="author-text"><a href="mailto:dee3@us.ibm.com">Eastlake, D.</a> and <a href="mailto:ogud@tislabs.com">O. Gudmundsson</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2538.txt">Storing Certificates in the Domain Name System (DNS)</a>", RFC 2538, March 1999.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2748">[19]</a></b></td> +<td class="author-text"><a href="mailto:David.Durham@intel.com">Durham, D.</a>, <a href="mailto:jboyle@Level3.net">Boyle, J.</a>, <a href="mailto:ronc@cisco.com">Cohen, R.</a>, <a href="mailto:herzog@iphighway.com">Herzog, S.</a>, <a href="mailto:rajan@research.att.com">Rajan, R.</a> and <a href="mailto:asastry@cisco.com">A. Sastry</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2748.txt">The COPS (Common Open Policy Service) Protocol</a>", RFC 2748, January 2000.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2663">[20]</a></b></td> +<td class="author-text"><a href="mailto:srisuresh@lucent.com">Srisuresh, P.</a> and <a href="mailto:holdrege@lucent.com">M. Holdrege</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2663.txt">IP Network Address Translator (NAT) Terminology and Considerations</a>", RFC 2663, August 1999.</td></tr> +</table> + +<a name="rfc.authors"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Authors' Addresses</h3> +<table width="99%" border="0" cellpadding="0" cellspacing="0"> +<tr><td class="author-text"> </td> +<td class="author-text">Michael C. Richardson</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Sandelman Software Works</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">470 Dawson Avenue</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Ottawa, ON K1Z 5V7</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">CA</td></tr> +<tr><td class="author" align="right">EMail: </td> +<td class="author-text"><a href="mailto:mcr@sandelman.ottawa.on.ca">mcr@sandelman.ottawa.on.ca</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://www.sandelman.ottawa.on.ca/">http://www.sandelman.ottawa.on.ca/</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">D. Hugh Redelmeier</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Mimosa</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Toronto, ON</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">CA</td></tr> +<tr><td class="author" align="right">EMail: </td> +<td class="author-text"><a href="mailto:hugh@mimosa.com">hugh@mimosa.com</a></td></tr> +</table> +<a name="rfc.copyright"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Full Copyright Statement</h3> +<p class='copyright'> +Copyright (C) The Internet Society (2003). All Rights Reserved.</p> +<p class='copyright'> +This document and translations of it may be copied and furnished to +others, and derivative works that comment on or otherwise explain it +or assist in its implementation may be prepared, copied, published and +distributed, in whole or in part, without restriction of any kind, +provided that the above copyright notice and this paragraph are +included on all such copies and derivative works. However, this +document itself may not be modified in any way, such as by removing +the copyright notice or references to the Internet Society or other +Internet organizations, except as needed for the purpose of +developing Internet standards in which case the procedures for +copyrights defined in the Internet Standards process must be +followed, or as required to translate it into languages other than +English.</p> +<p class='copyright'> +The limited permissions granted above are perpetual and will not be +revoked by the Internet Society or its successors or assigns.</p> +<p class='copyright'> +This document and the information contained herein is provided on an +"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING +TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING +BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION +HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF +MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p> +<h3>Acknowledgement</h3> +<p class='copyright'> +Funding for the RFC Editor function is currently provided by the +Internet Society.</p> +</font></body></html> diff --git a/doc/src/draft-richardson-ipsec-opportunistic.xml b/doc/src/draft-richardson-ipsec-opportunistic.xml new file mode 100644 index 000000000..d587df693 --- /dev/null +++ b/doc/src/draft-richardson-ipsec-opportunistic.xml @@ -0,0 +1,2519 @@ +<?xml version="1.0"?> +<!DOCTYPE rfc SYSTEM "rfc2629.dtd"> +<?rfc toc="yes"?> +<?rfc tocdepth='2' ?> + +<rfc ipr="full2026" docName="draft-richardson-ipsec-opportunistic-12.txt"> + +<front> + <area>Security</area> + <workgroup>Independent submission</workgroup> + <title abbrev="opportunistic"> + Opportunistic Encryption using The Internet Key Exchange (IKE) + </title> + + <author initials="M." surname="Richardson" fullname="Michael C. Richardson"> + <organization abbrev="SSW">Sandelman Software Works</organization> + <address> + <postal> + <street>470 Dawson Avenue</street> + <city>Ottawa</city> + <region>ON</region> + <code>K1Z 5V7</code> + <country>CA</country> + </postal> + <email>mcr@sandelman.ottawa.on.ca</email> + <uri>http://www.sandelman.ottawa.on.ca/</uri> + </address> + </author> + + <author initials="D.H." surname="Redelmeier" + fullname="D. Hugh Redelmeier"> + <organization abbrev="Mimosa">Mimosa</organization> + <address> + <postal> + <city>Toronto</city> + <region>ON</region> + <country>CA</country> + </postal> + <email>hugh@mimosa.com</email> + </address> + </author> + + <date month="June" year="2003"></date> + +<abstract> + <t> +This document describes opportunistic encryption (OE) using the Internet Key +Exchange (IKE) and IPsec. +Each system administrator adds new +resource records to his or her Domain Name System (DNS) to support +opportunistic encryption. The objective is to allow encryption for secure communication without +any pre-arrangement specific to the pair of systems involved. + </t> + <t> +DNS is used to distribute the public keys of each +system involved. This is resistant to passive attacks. The use of DNS +Security (DNSSEC) secures this system against active attackers as well. + </t> + <t> +As a result, the administrative overhead is reduced +from the square of the number of systems to a linear dependence, and it becomes +possible to make secure communication the default even +when the partner is not known in advance. + </t> + <t> +This document is offered up as an Informational RFC. + </t> +</abstract> + +</front> + +<middle> + +<section title="Introduction"> + +<section title="Motivation"> + +<t> +The objective of opportunistic encryption is to allow encryption without +any pre-arrangement specific to the pair of systems involved. Each +system administrator adds +public key information to DNS records to support opportunistic +encryption and then enables this feature in the nodes' IPsec stack. +Once this is done, any two such nodes can communicate securely. +</t> + +<t> +This document describes opportunistic encryption as designed and +implemented by the Linux FreeS/WAN project in revisions up and including 2.00. +Note that 2.01 and beyond implements RFC3445, in a backward compatible way. +For project information, see http://www.freeswan.org. +</t> + + <t> +The Internet Architecture Board (IAB) and Internet Engineering +Steering Group (IESG) have taken a strong stand that the Internet +should use powerful encryption to provide security and +privacy <xref target="RFC1984" />. +The Linux FreeS/WAN project attempts to provide a practical means to implement this policy. + </t> + + <t> +The project uses the IPsec, ISAKMP/IKE, DNS and DNSSEC +protocols because they are +standardized, widely available and can often be deployed very easily +without changing hardware or software or retraining users. + </t> + + <t> +The extensions to support opportunistic encryption are simple. No +changes to any on-the-wire formats are needed. The only changes are to +the policy decision making system. This means that opportunistic +encryption can be implemented with very minimal changes to an existing +IPsec implementation. + </t> + + <t> +Opportunistic encryption creates a "fax effect". The proliferation +of the fax machine was possible because it did not require that everyone +buy one overnight. Instead, as each person installed one, the value +of having one increased - as there were more people that could receive faxes. +Once opportunistic encryption is installed it +automatically recognizes +other boxes using opportunistic encryption, without any further configuration +by the network +administrator. So, as opportunistic encryption software is installed on more +boxes, its value +as a tool increases. +</t> + + <t> +This document describes the infrastructure to permit deployment of +Opportunistic Encryption. +</t> + + <t> +The term S/WAN is a trademark of RSA Data Systems, and is used with permission +by this project. + </t> + +</section> + +<section title="Types of network traffic"> + <t> + To aid in understanding the relationship between security processing and IPsec + we divide network traffic into four categories: + <list style="hanging"> + <t hangText="* Deny:"> networks to which traffic is always forbidden.</t> + <t hangText="* Permit:"> networks to which traffic in the clear is permitted.</t> + <t hangText="* Opportunistic tunnel:"> networks to which traffic is encrypted if possible, but otherwise is in the clear + or fails depending on the default policy in place. + </t> + <t hangText="* Configured tunnel:"> networks to which traffic +must be encrypted, and traffic in the clear is never permitted. +A Virtual Private Network (VPN) is a form of configured tunnel. +</t> + </list> + </t> + +<t> +Traditional firewall devices handle the first two categories. +No authentication is required. +The permit policy is currently the default on the Internet. +</t> + +<t> +This document describes the third category - opportunistic tunnel, which is +proposed as the new default for the Internet. +</t> + +<t> + Category four, encrypt traffic or drop it, requires authentication of the + end points. As the number of end points is typically bounded and is typically + under a single authority, arranging for distribution of + authentication material, while difficult, does not require any new + technology. The mechanism described here provides an additional way to + distribute the authentication materials, that of a public key method that does not + require deployment of an X.509 based infrastructure. +</t> +<t> +Current Virtual Private Networks can often be replaced by an "OE paranoid" +policy as described herein. +</t> +</section> + +<section title="Peer authentication in opportunistic encryption"> + + <t> + Opportunistic encryption creates tunnels between nodes that + are essentially strangers. This is done without any prior bilateral + arrangement. + There is, therefore, the difficult question of how one knows to whom one is + talking. + </t> + + <t> + One possible answer is that since no useful + authentication can be done, none should be tried. This mode of operation is + named "anonymous encryption". An active man-in-the-middle attack can be + used to thwart the privacy of this type of communication. + Without peer authentication, there is no way to prevent this kind of attack. + </t> + + <t> +Although a useful mode, anonymous encryption is not the goal of this +project. Simpler methods are available that can achieve anonymous +encryption only, but authentication of the peer is a desireable goal. +The latter is achieved through key distribution in DNS, leveraging upon +the authentication of the DNS in DNSSEC. +</t> + + <t> + Peers are, therefore, authenticated with DNSSEC when available. Local policy +determines how much trust to extend when DNSSEC is not available. + </t> + + <t> + However, an essential premise of building private connections with + strangers is that datagrams received through opportunistic tunnels + are no more special than datagrams that arrive in the clear. + Unlike in a VPN, these datagrams should not be given any special + exceptions when it comes to auditing, further authentication or + firewalling. + </t> + + <t> + When initiating outbound opportunistic encryption, local + configuration determines what happens if tunnel setup fails. It may be that + the packet goes out in the clear, or it may be dropped. + </t> + + </section> + +<section title="Use of RFC2119 terms"> +<t> + The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, + SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this + document, are to be interpreted as described in <xref target="RFC2119" /> +</t> +</section> + +</section> + +<section title="Overview"> + + <section title="Reference diagram"> + + <figure anchor="networkdiagram" title="Reference Network Diagram"> + <preamble>The following network diagram is used in the rest of + this document as the canonical diagram:</preamble> + <artwork> + [Q] [R] + . . AS2 + [A]----+----[SG-A].......+....+.......[SG-B]-------[B] + | ...... + AS1 | ..PI.. + | ...... + [D]----+----[SG-D].......+....+.......[C] AS3 + + + </artwork> + <postamble></postamble> + + </figure> + + <t> + In this diagram, there are four end-nodes: A, B, C and D. + There are three security gateways, SG-A, SG-B, SG-D. A, D, SG-A and + SG-D are part + of the same administrative authority, AS1. SG-A and SG-D are on two + different exit + paths from organization 1. SG-B/B is an independent organization, AS2. + Nodes Q and R are nodes on the Internet. PI is the Public + Internet ("The Wild"). + </t> + + </section> + + <section title="Terminology"> + + <t> + The following terminology is used in this document: + </t> + + <list style="hanging"> + <t hangText="Security gateway (or simply gateway):"> a system that performs IPsec tunnel + mode encapsulation/decapsulation. [SG-x] in the diagram.</t> + <t hangText="Alice:"> node [A] in the diagram. When an IP address is needed, this is 192.1.0.65.</t> + <t hangText="Bob:"> node [B] in the diagram. When an IP address is needed, this is 192.2.0.66.</t> + <t hangText="Carol:"> node [C] in the diagram. When an IP address is needed, this is 192.1.1.67.</t> + <t hangText="Dave:"> node [D] in the diagram. When an IP address is needed, this is 192.3.0.68.</t> + <t hangText="SG-A:"> Alice's security gateway. Internally it is 192.1.0.1, externally it is 192.1.1.4.</t> + <t hangText="SG-B:"> Bob's security gateway. Internally it is 192.2.0.1, externally it is 192.1.1.5.</t> + <t hangText="SG-D:"> Dave's security gateway. Also Alice's backup security gateway. Internally it is 192.3.0.1, externally it is 192.1.1.6.</t> + <t hangText="."> A period represents an untrusted network of unknown + type.</t> + <t hangText="Configured tunnel:"> a tunnel that + is directly and deliberately hand configured on participating gateways. + Configured tunnels are typically given a higher level of + trust than opportunistic tunnels.</t> + + <t hangText="Road warrior tunnel:"> a configured tunnel connecting one + node with a fixed IP address and one node with a variable IP address. + A road warrior (RW) connection must be initiated by the + variable node, since the fixed node cannot know the + current address for the road warrior. </t> + + <t hangText="Anonymous encryption:"> + the process of encrypting a session without any knowledge of who the + other parties are. No authentication of identities is done.</t> + + <t hangText="Opportunistic encryption:"> + the process of encrypting a session with authenticated knowledge of + who the other party is.</t> + + <t hangText="Lifetime:"> + the period in seconds (bytes or datagrams) for which a security + association will remain alive before needing to be re-keyed.</t> + + <t hangText="Lifespan:"> + the effective time for which a security association remains useful. A + security association with a lifespan shorter than its lifetime would + be removed when no longer needed. A security association with a + lifespan longer than its lifetime would need to be re-keyed one or + more times.</t> + + <t hangText="Phase 1 SA:"> an ISAKMP/IKE security association sometimes + referred to as a keying channel.</t> + + <t hangText="Phase 2 SA:"> an IPsec security association.</t> + + <t hangText="Tunnel:"> another term for a set of phase 2 SA (one in each direction).</t> + + <t hangText="NAT:"> Network Address Translation + (see <xref target="RFC2663" />).</t> + + <t hangText="NAPT:"> Network Address and Port Translation + (see <xref target="RFC2663" />).</t> + + <t hangText="AS:"> an autonomous system </t> + + <t hangText="FQDN:"> Fully-Qualified Domain Name </t> + + <t hangText="Default-free zone:"> + a set of routers that maintain a complete set of routes to + all currently reachable destinations. Having such a list, these routers + never make use of a default route. A datagram with a destination address + not matching any route will be dropped by such a router. + </t> + + </list> + </section> + +<section title="Model of operation"> + +<t> +The opportunistic encryption security gateway (OE gateway) is a regular +gateway node as described in <xref target="RFC0791" /> section 2.4 and +<xref target="RFC1009" /> with the additional capabilities described here and +in <xref target="RFC2401" />. +The algorithm described here provides a way to determine, for each datagram, +whether or not to encrypt and tunnel the datagram. Two important things +that must be determined are whether or not to encrypt and tunnel and, if +so, the destination address or name of the tunnel end point which should be used. +</t> + +<section title="Tunnel authorization"> +<t> +The OE gateway determines whether or not to create a tunnel based on +the destination address of each packet. Upon receiving a packet with a destination +address not recently seen, the OE gateway performs a lookup in DNS for an +authorization resource record (see <xref target="TXT"/>). The record is located using +the IP address to perform a search in the in-addr.arpa (IPv4) or ip6.arpa +(IPv6) maps. If an authorization record is found, the OE gateway +interprets this as a request for a tunnel to be formed. +</t> +</section> + +<section title="Tunnel end-point discovery"> + +<t> +The authorization resource record also provides the address or name of the tunnel +end point which should be used. +</t> +<t> +The record may also provide the public RSA key of the tunnel end point +itself. This is provided for efficiency only. If the public RSA key is not +present, the OE gateway performs a second lookup to find a KEY +resource record for the end point address or name. +</t> +<t> +Origin and integrity protection of the resource records is provided by +DNSSEC (<xref target="RFC2535"/>). <xref target="nodnssec"/> +documents an optional restriction on the tunnel end point if DNSSEC signatures +are not available for the relevant records. +</t> + +</section> + +<section title="Caching of authorization results"> +<t> +The OE gateway maintains a cache, in the forwarding plane, of +source/destination pairs for which opportunistic encryption has been +attempted. This cache maintains a record of whether or not OE was +successful so that subsequent datagrams can be forwarded properly +without additional delay. +</t> + +<t> +Successful negotiation of OE instantiates a new security association. +Failure to negotiate OE results in creation of a +forwarding policy entry either to drop or transmit in the clear future +datagrams. This negative cache is necessary to avoid the possibly lengthy process of repeatedly looking +up the same information. +</t> + +<t> +The cache is timed out periodically, as described in <xref target="teardown" />. +This removes entries that are no longer +being used and permits the discovery of changes in authorization policy. +</t> +</section> + +</section> <!-- "Model of operation" --> + +</section> <!-- "Overview" --> + +<section title="Protocol Specification"> + +<t> +The OE gateway is modeled to have a forwarding plane and a control +plane. A control channel, such as PF_KEY, connects the two planes. +(See <xref target="RFC2367" />.) +The forwarding plane performs per datagram operations. The control plane +contains a keying daemon, such as ISAKMP/IKE, and performs all +authorization, peer authentication and key derivation functions. +</t> + +<section title="Forwarding plane state machine"> + +<t> +Let the OE gateway maintain a collection of objects -- a superset of the +security policy database (SPD) specified in <xref target="RFC2401" />. For +each combination of source and destination address, an SPD +object exists in one of five following states. +Prior to forwarding each datagram, the responder uses the source and +destination addresses to pick an entry from the SPD. +The SPD then determines if and how the packet is forwarded. +</t> + +<!-- from file forwardingstate.txt --> +<artwork><![CDATA[ + .--------------. + | non-existant | + | policy | + `--------------' + | + | PF_ACQUIRE + | + |<---------. + V | new packet + .--------------. | (maybe resend PF_ACQUIRE) + | hold policy |--' + | |--. + `--------------' \ pass + | | \ msg .---------. + | | \ V | forward + | | .-------------. | packet + create | | | pass policy |--' + IPsec | | `-------------' + SA | | + | \ + | \ + V \ deny + .---------. \ msg + | encrypt | \ + | policy | \ ,---------. + `---------' \ | | discard + \ V | packet + .-------------. | + | deny policy |--' + '-------------' +]]></artwork> + + +<section title="Non-existent policy"> +<t> +If the gateway does not find an entry, then this policy applies. +The gateway creates an entry with an initial state of "hold policy" and requests +keying material from the keying daemon. The gateway does not forward the datagram, +rather it SHOULD attach the datagram to the SPD entry as the "first" datagram and retain it +for eventual transmission in a new state. + +</t> +</section> + +<section title="Hold policy"> +<t> +The gateway requests keying material. If the interface to the keying +system is lossy (PF_KEY, for instance, can be), the implementation +SHOULD include a mechanism to retransmit the +keying request at a rate limited to less than 1 request per second. +The gateway does not forward the datagram. The gateway SHOULD attach the +datagram to the SPD entry as the "last" datagram where it is retained +for eventual transmission. +If there is a datagram already so stored, then that already stored datagram is discarded. +</t> +<t> +The rational behind saving the the "first" and "last" datagrams are as follows: +The "first" datagram is probably a TCP SYN packet. Once there is keying +established, the gateway will release this datagram, avoiding the need to +for the end-point to retransmit the datagram. In the case where the connection +was not a TCP connection, buyt was instead a streaming protocol or a DNS request, +the "last" datagram that was retained is likely the most recent data. The difference +between "first" and "last" may also help the end-points determine +which data awas dropped while negotiation took place. +</t> +</section> + +<section title="Pass-through policy"> +<t> +The gateway forwards the datagram using the normal forwarding table. +The gateway enters this state only by command from the keying daemon, +and upon entering this state, also forwards the "first" and "last" datagrams. +</t> +</section> + +<section title="Deny policy"> +<t> +The gateway discards the datagram. The gateway enters this state only by +command +from the keying daemon, and upon entering this state, discards the "first" +and "last" datagrams. +An implementation MAY provide the administator with a control to determine +if further datagrams cause ICMP messages +to be generated (i.e. ICMP Destination Unreachable, Communication +Administratively Prohibited. type=3, code=13). +</t> +</section> + +<section title="Encrypt policy"> +<t> +The gateway encrypts the datagram using the indicated security association database +(SAD) entry. The gateway enters this state only by command from the keying daemon, and upon entering +this state, releases and forwards the "first" and "last" datagrams using the +new encrypt policy. +</t> +<t> +If the associated SAD entry expires because of byte, packet or time limits, then +the entry returns to the Hold policy, and an expire message is sent to the keying daemon. +</t> +</section> + +<t> +All states may be created directly by the keying daemon while acting as a +gateway. +</t> + +</section> <!-- "Datagram state machine" --> + + +<section anchor="initclasses" title="Keying Daemon -- initiator"> +<t> +Let the keying daemon maintain a collection of objects. Let them be +called "connections" or "conn"s. There are two categories of +connection objects: classes and instances. A class represents an +abstract policy - what could be. An instance represents an actual connection - +what is implemented at the time. +</t> + +<t> +Let there be two further subtypes of connections: keying channels (Phase +1 SAs) and data channels (Phase 2 SAs). Each data channel object may have +a corresponding SPD and SAD entry maintained by the datagram state machine. +</t> + +<t> +For the purposes of opportunistic encryption, there MUST, at least, be +connection classes known as "deny", "always-clear-text", "OE-permissive", and +"OE-paranoid". +The latter two connection classes define a set of source and/or destination +addresses for which opportunistic encryption will be attempted. +The administrator MAY set policy options in a number of additional places. +An implementation MAY create additional connection classes to further refine +these policies. +</t> + +<t> +The simplest system may need only the "OE-permissive" connection, and would +list its own (single) IP address as the source address of this policy and +the wild-card address 0.0.0.0/0 as the destination IPv4 address. That is, the +simplest policy is to try opportunistic encryption with all destinations. +</t> + +<t> +The distinction between permissive and paranoid OE use will become clear +in the state transition differences. In general a permissive OE will, on +failure, install a pass-through policy, while a paranoid OE will, on failure, +install a drop policy. +</t> + +<t> +In this description of the keying machine's state transitions, the states +associated with the keying system itself are omitted because they are best documented in the keying system +(<xref target="RFC2407" />, +<xref target="RFC2408" /> and <xref target="RFC2409" /> for ISAKMP/IKE), +and the details are keying system specific. Opportunistic encryption is not +dependent upon any specific keying protocol, but this document does provide +requirements for those using ISAKMP/IKE to assure that implementations inter-operate. +</t> +<t> +The state transitions that may be involved in communicating with the +forwarding plane are omitted. PF_KEY and similar protocols have their own +set of states required for message sends and completion notifications. +</t> +<t> +Finally, the retransmits and recursive lookups that are normal for DNS are +not included in this description of the state machine. +</t> + +<!-- from file initiatorstate.txt --> +<artwork><![CDATA[ + + | + | PF_ACQUIRE + | + V + .---------------. + | non-existant | + | connection | + `---------------' + | | | + send , | \ +expired pass / | \ send +conn. msg / | \ deny + ^ / | \ msg + | V | do \ +.---------------. | DNS \ .---------------. +| clear-text | | lookup `->| deny |---> expired +| connection | | for | connection | connection +`---------------' | destination `---------------' + ^ ^ | ^ + | | no record | | + | | OE-permissive V | no record + | | .---------------. | OE-paranoid + | `------------| potential OE |---------' + | | connection | ^ + | `---------------' | + | | | + | | got TXT record | DNSSEC failure + | | reply | + | V | wrong + | .---------------. | failure + | | authenticate |---------' + | | & parse TXT RR| ^ + | repeated `---------------' | + | ICMP | | + | failures | initiate IKE to | + | (short-timeout) | responder | + | V | + | phase-2 .---------------. | failure + | failure | pending |---------' + | (normal | OE | ^ + | timeout) | |invalid | phase-2 failure (short-timeout) + | | |<--.SPI | ICMP failures (normal timeout) + | | | | | + | | +=======+ |---' | + | | | IKE | | ^ | + `--------------| | states|---------------' + | +=======+ | | + `---------------' | + | IPsec SA | invalid SPI + | established | + V | rekey time + .--------------. | + | keyed |<---|-------------------------------. + | connection |----' | + `--------------' | + | timer | + | | + V | + .--------------. connection still active | + clear-text----->| expired |------------------------------------' + deny----->| connection | + `--------------' + | dead connected - deleted + V +]]></artwork> + + +<section title="Nonexistent connection"> +<t> +There is no connection instance for a given source/destination address pair. +Upon receipt of a request for keying material for this +source/destination pair, the initiator searches through the connection classes to +determine the most appropriate policy. Upon determining an appropriate +connection class, an instance object is created of that type. +Both of the OE types result in a potential OE connection. +</t> +<t>Failure to find an appropriate connection class results in an +administrator defined default. +</t> +<t> +In each case, when the initiator finds an appropriate class for the new flow, +an instance connection is made of the class which matched. +</t> +</section> + +<section title="Clear-text connection"> +<t> +The non-existent connection makes a transition to this state when an +always-clear-text class is instantiated, or when an OE-permissive +connection fails. During the transition, the initiator creates a pass-through +policy object in the forwarding plane for the appropriate flow. +</t> +<t> +Timing out is the only way to leave this state +(see <xref target="expiring" />). +</t> +</section> + +<section title="Deny connection"> +<t> +The empty connection makes a transition to this state when a +deny class is instantiated, or when an OE-paranoid connection fails. +During the transition, the initiator creates a deny policy object in the forwarding plane +for the appropriate flow. +</t> +<t> +Timing out is the only way to leave this state +(see <xref target="expiring" />). +</t> +</section> + +<section title="Potential OE connection"> +<t> +The empty connection makes a transition to this state when one of either OE class is instantiated. +During the transition to this state, the initiator creates a hold policy object in the +forwarding plane for the appropriate flow. +</t> +<t> +In addition, when making a transition into this state, DNS lookup is done in +the reverse-map for a TXT delegation resource record (see <xref target="TXT" />). +The lookup key is the destination address of the flow. +</t> +<t> +There are three ways to exit this state: +<list style="numbers"> +<t>DNS lookup finds a TXT delegation resource record.</t> +<t>DNS lookup does not find a TXT delegation resource record.</t> +<t>DNS lookup times out.</t> +</list> +</t> + +<t> +Based upon the results of the DNS lookup, the potential OE connection makes a +transition to the pending OE connection state. The conditions for a +successful DNS look are: +<list style="numbers"> +<t>DNS finds an appropriate resource record</t> +<t>It is properly formatted according to <xref target="TXT" /></t> +<t> if DNSSEC is enabled, then the signature has been vouched for.</t> +</list> + +Note that if the initiator does not find the public key +present in the TXT delegation record, then the public key must +be looked up as a sub-state. Only successful completion of all the +DNS lookups is considered a success. +</t> +<t> +If DNS lookup does not find a resource record or DNS times out, then the +initiator considers the receiver not OE capable. If this is an OE-paranoid instance, +then the potential OE connection makes a transition to the deny connection state. +If this is an OE-permissive instance, then the potential OE connection makes a transition to the +clear-text connection state. +</t> +<t> +If the initiator finds a resource record but it is not properly formatted, or +if DNSSEC is +enabled and reports a failure to authenticate, then the potential OE +connection makes a +transition to the deny connection state. This action SHOULD be logged. If the +administrator wishes to override this transition between states, then an +always-clear class can be installed for this flow. An implementation MAY make +this situation a new class. +</t> + +<section anchor="nodnssec" title="Restriction on unauthenticated TXT delegation records"> +<t> +An implementation SHOULD also provide an additional administrative control +on delegation records and DNSSEC. This control would apply to delegation +records (the TXT records in the reverse-map) that are not protected by +DNSSEC. +Records of this type are only permitted to delegate to their own address as +a gateway. When this option is enabled, an active attack on DNS will be +unable to redirect packets to other than the original destination. +<!-- This was asked for by Bill Sommerfeld --> +</t> +</section> +</section> + +<section title="Pending OE connection"> +<t> +The potential OE connection makes a transition to this state when +the initiator determines that all the information required from the DNS lookup is present. +Upon entering this state, the initiator attempts to initiate keying to the gateway +provided. +</t> +<t> +Exit from this state occurs either with a successfully created IPsec SA, or +with a failure of some kind. Successful SA creation results in a transition +to the key connection state. +</t> +<t> +Three failures have caused significant problems. They are clearly not the +only possible failures from keying. +</t> +<t> +Note that if there are multiple gateways available in the TXT delegation +records, then a failure can only be declared after all have been +tried. Further, creation of a phase 1 SA does not constitute success. A set +of phase 2 SAs (a tunnel) is considered success. +</t> +<t> +The first failure occurs when an ICMP port unreachable is consistently received +without any other communication, or when there is silence from the remote +end. This usually means that either the gateway is not alive, or the +keying daemon is not functional. For an OE-permissive connection, the initiator makes a transition +to the clear-text connection but with a low lifespan. For an OE-pessimistic connection, +the initiator makes a transition to the deny connection again with a low lifespan. The +lifespan in both +cases is kept low because the remote gateway may +be in the process of rebooting or be otherwise temporarily unavailable. +</t> +<t> +The length of time to wait for the remote keying daemon to wake up is +a matter of some debate. If there is a routing failure, 5 minutes is usually long +enough for the network to +re-converge. Many systems can reboot in that amount of +time as well. However, 5 minutes is far too long for most users to wait to +hear that they can not connect using OE. Implementations SHOULD make this a +tunable parameter. +</t> +<t> +The second failure occurs after a phase 1 SA has been created, but there is +either no response to the phase 2 proposal, or the initiator receives a +negative notify (the notify must be +authenticated). The remote gateway is not prepared to do OE at this time. +As before, the initiator makes a transition to the clear-text or the deny +connection based upon connection class, but this +time with a normal lifespan. +</t> +<t> +The third failure occurs when there is signature failure while authenticating +the remote gateway. This can occur when there has been a +key roll-over, but DNS has not caught up. In this case again, the initiator makes a +transition to the clear-text or the deny connection based +upon the connection class. However, the lifespan depends upon the remaining +time to live in the DNS. (Note that DNSSEC signed resource records have a different +expiry time than non-signed records.) +<!-- dig @gateway would also work here --> +</t> + +</section> + +<section anchor="keyed" title="Keyed connection"> +<t> +The pending OE connection makes a transition to this state when +session keying material (the phase 2 SAs) is derived. The initiator creates an encrypt +policy in the forwarding plane for this flow. +</t> +<t> +There are three ways to exit this state. The first is by receipt of an +authenticated delete message (via the keying channel) from the peer. This is +normal teardown and results in a transition to the expired connection state. +</t> +<t> +The second exit is by expiry of the forwarding plane keying material. This +starts a re-key operation with a transition back to pending OE +connection. In general, the soft expiry occurs with sufficient time left +to continue to use the keys. A re-key can fail, which may +result in the connection failing to clear-text or deny as +appropriate. In the event of a failure, the forwarding plane +policy does not change until the phase 2 SA (IPsec SA) reaches its +hard expiry. +</t> +<t> +The third exit is in response to a negotiation from a remote +gateway. If the forwarding plane signals the control plane that it has received an +unknown SPI from the remote gateway, or an ICMP is received from the remote gateway +indicating an unknown SPI, the initiator should consider that +the remote gateway has rebooted or restarted. Since these +indications are easily forged, the implementation must +exercise care. The initiator should make a cautious +(rate-limited) attempt to re-key the connection. +</t> +</section> + +<section anchor="expiring" title="Expiring connection"> +<t> +The initiator will periodically place each of the deny, clear-text, and keyed +connections into this +sub-state. See <xref target="teardown" /> for more details of how often this +occurs. +The initiator queries the forwarding plane for last use time of the +appropriate +policy. If the last use time is relatively recent, then the connection +returns to the +previous deny, clear-text or keyed connection state. If not, then the +connection enters +the expired connection state. +</t> +<t> +The DNS query and answer that lead to the expiring connection state are also +examined. The DNS query may become stale. (A negative, i.e. no such record, answer +is valid for the period of time given by the MINIMUM field in an attached SOA +record. See <xref target="RFC1034" /> section 4.3.4.) +If the DNS query is stale, then a new query is made. If the results change, then the connection +makes a transition to a new state as described in potential OE connection state. +</t> +<t> +Note that when considering how stale a connection is, both outgoing SPD and +incoming SAD must be queried as some flows may be unidirectional for some time. +</t> +<t> +Also note that the policy at the forwarding plane is not updated unless there +is a conclusion that there should be a change. +</t> + +</section> +<section title="Expired connection"> +<t> +Entry to this state occurs when no datagrams have been forwarded recently via the +appropriate SPD and SAD objects. The objects in the forwarding plane are +removed (logging any final byte and packet counts if appropriate) and the +connection instance in the keying plane is deleted. +</t> +<t> +The initiator sends an ISAKMP/IKE delete to clean up the phase 2 SAs as described in +<xref target="teardown" />. +</t> +<t> +Whether or not to delete the phase 1 SAs +at this time is left as a local implementation issue. Implementations +that do delete the phase 1 SAs MUST send authenticated delete messages to +indicate that they are doing so. There is an advantage to keeping +the phase 1 SAs until they expire - they may prove useful again in the +near future. +</t> +</section> + +</section> <!-- "Keying state machine - initiator" --> + +<section title="Keying Daemon - responder"> +<t> +The responder has a set of objects identical to those of the initiator. +</t> +<t> +The responder receives an invitation to create a keying channel from an initiator. +</t> + +<!-- from file responderstate.txt --> +<artwork><![CDATA[ + | + | IKE main mode + | phase 1 + V + .-----------------. + | unauthenticated | + | OE peer | + `-----------------' + | + | lookup KEY RR in in-addr.arpa + | (if ID_IPV4_ADDR) + | lookup KEY RR in forward + | (if ID_FQDN) + V + .-----------------. RR not found + | received DNS |---------------> log failure + | reply | + `----+--------+---' + phase 2 | \ misformatted + proposal | `------------------> log failure + V + .----------------. + | authenticated | identical initiator + | OE peer |--------------------> initiator + `----------------' connection found state machine + | + | look for TXT record for initiator + | + V + .---------------. + | authorized |---------------------> log failure + | OE peer | + `---------------' + | + | + V + potential OE + connection in + initiator state + machine + + +$Id: draft-richardson-ipsec-opportunistic.xml,v 1.1 2004/03/15 20:35:24 as Exp $ +]]></artwork> + + +<section title="Unauthenticated OE peer"> +<t> +Upon entering this state, the responder starts a DNS lookup for a KEY record for the +initiator. +The responder looks in the reverse-map for a KEY record for the initiator if the +initiator has offered an ID_IPV4_ADDR, and in the forward map if the +initiator has offered an ID_FQDN type. (See <xref target="RFC2407" /> section +4.6.2.1.) +</t> +<t> +The responder exits this state upon successful receipt of a KEY from DNS, and use of the key +to verify the signature of the initiator. +</t> + +<!-- +<t> +The public key that is retrieved should be stored in stable storage for an +administratively defined period of time, (typically several months if +possible). If a key has previously been stored on disk, then the returned key +should be compared to what has been received, and the key considered valid +only if they match. +</t> +--> + +<t> +Successful authentication of the peer results in a transition to the +authenticated OE Peer state. +</t> +<t> +Note that the unauthenticated OE peer state generally occurs in the middle of the key negotiation +protocol. It is really a form of pseudo-state. +</t> +</section> + +<section title="Authenticated OE Peer"> +<t> +The peer will eventually propose one or more phase 2 SAs. The responder uses the source and +destination address in the proposal to +finish instantiating the connection state +using the connection class table. +The responder MUST search for an identical connection object at this point. +</t> +<t> +If an identical connection is found, then the responder deletes the old instance, +and the new object makes a transition to the pending OE connection state. This means +that new ISAKMP connections with a given peer will always use the latest +instance, which is the correct one if the peer has rebooted in the interim. +</t> +<t> +If an identical connection is not found, then the responder makes the transition according to the +rules given for the initiator. +</t> +<t> +Note that if the initiator is in OE-paranoid mode and the responder is in +either always-clear-text or deny, then no communication is possible according +to policy. An implementation is permitted to create new types of policies +such as "accept OE but do not initiate it". This is a local matter. + </t> +</section> + +</section> <!-- "Keying state machine - responder" --> + +<section anchor="teardown" title="Renewal and teardown"> + <section title="Aging"> +<t> +A potentially unlimited number of tunnels may exist. In practice, only a few +tunnels are used during a period of time. Unused tunnels MUST, therefore, be +torn down. Detecting when tunnels are no longer in use is the subject of this section. +</t> + +<t> +There are two methods for removing tunnels: explicit deletion or expiry. +</t> + +<t> +Explicit deletion requires an IKE delete message. As the deletes +MUST be authenticated, both ends of the tunnel must maintain the +key channel (phase 1 ISAKMP SA). An implementation which refuses to either maintain or +recreate the keying channel SA will be unable to use this method. +</t> + +<t> +The tunnel expiry method simply allows the IKE daemon to +expire normally without attempting to re-key it. +</t> + +<t> +Regardless of which method is used to remove tunnels, the implementation MUST +a method to determine if the tunnel is still in use. The specifics are a +local matter, but the FreeS/WAN project uses the following criteria. These +criteria are currently implemented in the key management daemon, but could +also be implemented at the SPD layer using an idle timer. +</t> + +<t> +Set a short initial (soft) lifespan of 1 minute since many net flows last +only a few seconds. +</t> + +<t> +At the end of the lifespan, check to see if the tunnel was used by +traffic in either direction during the last 30 seconds. If so, assign a +longer tentative lifespan of 20 minutes after which, look again. If the +tunnel is not in use, then close the tunnel. +</t> + +<t> +The expiring state in the key management +system (see <xref target="expiring" />) implements these timeouts. +The timer above may be in the forwarding plane, +but then it must be re-settable. +</t> + +<t> +The tentative lifespan is independent of re-keying; it is just the time when +the tunnel's future is next considered. +(The term lifespan is used here rather than lifetime for this reason.) +Unlike re-keying, this tunnel use check is not costly and should happen +reasonably frequently. +</t> + +<t> +A multi-step back-off algorithm is not considered worth the effort here. +</t> + +<t> +If the security gateway and the client host are the +same and not a Bump-in-the-Stack or Bump-in-the-Wire implementation, tunnel +teardown decisions MAY pay attention to TCP connection status as reported +by the local TCP layer. A still-open TCP connection is almost a guarantee that more traffic is +expected. Closing of the only TCP connection through a tunnel is a +strong hint that no more traffic is expected. +</t> + +</section> <!-- "Aging" --> + +<section title="Teardown and cleanup"> + +<t> +Teardown should always be coordinated between the two ends of the tunnel by +interpreting and sending delete notifications. There is a +detailed sub-state in the expired connection state of the key manager that +relates to retransmits of the delete notifications, but this is considered to +be a keying system detail. +</t> + +<t> +On receiving a delete for the outbound SAs of a tunnel (or some subset of +them), tear down the inbound ones also and notify the remote end with a +delete. If the local system receives a delete for a tunnel which is no longer in +existence, then two delete messages have crossed paths. Ignore the delete. +The operation has already been completed. Do not generate any messages in this +situation. +</t> +<t> +Tunnels are to be considered as bidirectional entities, even though the +low-level protocols don't treat them this way. +</t> + +<t> +When the deletion is initiated locally, rather than as a +response to a received delete, send a delete for (all) the +inbound SAs of a tunnel. If the local system does not receive a responding delete +for the outbound SAs, try re-sending the original +delete. Three tries spaced 10 seconds apart seems a reasonable +level of effort. A failure of the other end to respond after 3 attempts, +indicates that the possibility of further communication is unlikely. Remove the outgoing SAs. +(The remote system may be a mobile node that is no longer present or powered on.) +</t> + +<t> +After re-keying, transmission should switch to using the new +outgoing SAs (ISAKMP or IPsec) immediately, and the old leftover +outgoing SAs should be cleared out promptly (delete should be sent +for the outgoing SAs) rather than waiting for them to expire. This +reduces clutter and minimizes confusion for the operator doing diagnostics. +</t> + +</section> + +</section> + +</section> <!-- "Specification" --> + +<section title="Impacts on IKE"> + + <section title="ISAKMP/IKE protocol"> + <t> + The IKE wire protocol needs no modifications. The major changes are + implementation issues relating to how the proposals are interpreted, and from + whom they may come. + </t> + <t> + As opportunistic encryption is designed to be useful between peers without + prior operator configuration, an IKE daemon must be prepared to negotiate + phase 1 SAs with any node. This may require a large amount of resources to + maintain cookie state, as well as large amounts of entropy for nonces, + cookies and so on. + </t> + <t> + The major changes to support opportunistic encryption are at the IKE daemon + level. These changes relate to handling of key acquisition requests, lookup + of public keys and TXT records, and interactions with firewalls and other + security facilities that may be co-resident on the same gateway. + </t> + </section> + + <section title="Gateway discovery process"> + <t> + In a typical configured tunnel, the address of SG-B is provided + via configuration. Furthermore, the mapping of an SPD entry to a gateway is + typically a 1:1 mapping. When the 0.0.0.0/0 SPD entry technique is used, then + the mapping to a gateway is determined by the reverse DNS records. + </t> + <t> + The need to do a DNS lookup and wait for a reply will typically introduce a + new state and a new event source (DNS replies) to IKE. Although a +synchronous DNS request can be implemented for proof of concept, experience +is that it can cause very high latencies when a queue of queries must +all timeout in series. + </t> + <t> + Use of an asynchronous DNS lookup will also permit overlap of DNS lookups with + some of the protocol steps. + </t> + </section> + + <section title="Self identification"> + <t> + SG-A will have to establish its identity. Use an + IPv4 ID in phase 1. + </t> + <t> There are many situations where the administrator of SG-A may not be + able to control the reverse DNS records for SG-A's public IP address. + Typical situations include dialup connections and most residential-type broadband Internet access + (ADSL, cable-modem) connections. In these situations, a fully qualified domain + name that is under the control of SG-A's administrator may be used + when acting as an initiator only. + The FQDN ID should be used in phase 1. See <xref target="fqdn" /> + for more details and restrictions. + </t> + </section> + + <section title="Public key retrieval process"> + <t> + Upon receipt of a phase 1 SA proposal with either an IPv4 (IPv6) ID or + an FQDN ID, an IKE daemon needs to examine local caches and + configuration files to determine if this is part of a configured tunnel. + If no configured tunnels are found, then the implementation should attempt to retrieve + a KEY record from the reverse DNS in the case of an IPv4/IPv6 ID, or + from the forward DNS in the case of FQDN ID. + </t> + <t> + It is reasonable that if other non-local sources of policy are used + (COPS, LDAP), they be consulted concurrently but some + clear ordering of policy be provided. Note that due to variances in + latency, implementations must wait for positive or negative replies from all sources + of policy before making any decisions. + </t> + </section> + + <section title="Interactions with DNSSEC"> + <t> + The implementation described (1.98) neither uses DNSSEC directly to + explicitly verify the authenticity of zone information, nor uses the NXT + records to provide authentication of the absence of a TXT or KEY + record. Rather, this implementation uses a trusted path to a DNSSEC + capable caching resolver. + </t> + <t> + To distinguish between an authenticated and an unauthenticated DNS + resource record, a stub resolver capable of returning DNSSEC + information MUST be used. + </t> + + </section> + +<!-- + <section title="Interactions with COPS"> + <t> + At this time there is no experience with implementations that interact + with COPS Policy Decision Points (PDP) <xref target="RFC2748" />. It is + suggested that it may be + appropriate for many of + the policy and discovery mechanisms outlined here to be done by a PDP. + In this context, the IKE daemon present in the Policy Enforcement Point + (PEP) may not need any modifications. + </t> + </section> +--> + + <section title="Required proposal types"> + + <section anchor="phase1id" title="Phase 1 parameters"> + <t> + Main mode MUST be used. + </t> + <t> + The initiator MUST offer at least one proposal using some combination + of: 3DES, HMAC-MD5 or HMAC-SHA1, DH group 2 or 5. Group 5 SHOULD be + proposed first. + <xref target="RFC3526" /> + </t> + <t> + The initiator MAY offer additional proposals, but the cipher MUST not + be weaker than 3DES. The initiator SHOULD limit the number of proposals + such that the IKE datagrams do not need to be fragmented. + </t> + <t> + The responder MUST accept one of the proposals. If any configuration + of the responder is required then the responder is not acting in an + opportunistic way. + </t> + <t> + The initiator SHOULD use an ID_IPV4_ADDR (ID_IPV6_ADDR for IPv6) of the external + interface of the initiator for phase 1. (There is an exception, see <xref + target="fqdn" />.) The authentication method MUST be RSA public key signatures. + The RSA key for the initiator SHOULD be placed into a DNS KEY record in + the reverse space of the initiator (i.e. using in-addr.arpa or + ip6.arpa). + </t> + </section> + + <section anchor="phase2id" title="Phase 2 parameters"> + <t> + The initiator MUST propose a tunnel between the ultimate + sender ("Alice" or "A") and ultimate recipient ("Bob" or "B") + using 3DES-CBC + mode, MD5 or SHA1 authentication. Perfect Forward Secrecy MUST be specified. + </t> + <t> + Tunnel mode MUST be used. + </t> + <t> + Identities MUST be ID_IPV4_ADDR_SUBNET with the mask being /32. + </t> + <t> + Authorization for the initiator to act on Alice's behalf is determined by + looking for a TXT record in the reverse-map at Alice's IP address. + </t> + <t> + Compression SHOULD NOT be mandatory. It MAY be offered as an option. + </t> + </section> + </section> + +</section> + +<section title="DNS issues"> + <section anchor="KEY" title="Use of KEY record"> + <t> + In order to establish their own identities, security gateways SHOULD publish + their public keys in their reverse DNS via + DNSSEC's KEY record. + See section 3 of <xref target="RFC2535">RFC 2535</xref>. + </t> + <t> + <preamble>For example:</preamble> + <artwork><![CDATA[ +KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8 +]]></artwork> + + <list style="hanging"> + <t hangText="0x4200:"> The flag bits, indicating that this key is prohibited + for confidentiality use (it authenticates the peer only, a separate + Diffie-Hellman exchange is used for + confidentiality), and that this key is associated with the non-zone entity + whose name is the RR owner name. No other flags are set.</t> + <t hangText="4:">This indicates that this key is for use by IPsec.</t> + <t hangText="1:">An RSA key is present.</t> + <t hangText="AQNJjkKlIk9...nYyUkKK8:">The public key of the host as described in <xref target="RFC3110" />.</t> + </list> + </t> + <t>Use of several KEY records allows for key rollover. The SIG Payload in + IKE phase 1 SHOULD be accepted if the public key given by any KEY RR + validates it. + </t> + </section> + + <section anchor="TXT" title="Use of TXT delegation record"> + <t> +If, for example, machine Alice wishes SG-A to act on her behalf, then +she publishes a TXT record to provide authorization for SG-A to act on +Alice's behalf. Similarly for Bob and SG-B. +</t> + +<t> +These records are located in the reverse DNS (in-addr.arpa or ip6.arpa) for their +respective IP addresses. The reverse DNS SHOULD be secured by DNSSEC. +DNSSEC is required to defend against active attacks. + </t> + <t> + If Alice's address is P.Q.R.S, then she can authorize another node to + act on her behalf by publishing records at: + <artwork><![CDATA[ +S.R.Q.P.in-addr.arpa + ]]></artwork> + </t> + + <t> + The contents of the resource record are expected to be a string that + uses the following syntax, as suggested in <xref target="RFC1464">RFC1464</xref>. + (Note that the reply to query may include other TXT resource + records used by other applications.) + + <figure anchor="txtformat" title="Format of reverse delegation record"> + <artwork><![CDATA[ +X-IPsec-Server(P)=A.B.C.D KEY + ]]></artwork> + </figure> + </t> + + where the record is formed by the following fields: + + <list style="hanging"> + <t hangText="P:"> Specifies a precedence for this record. This is + similar to MX record preferences. Lower numbers have stronger + preference. + </t> + + <t hangText="A.B.C.D:"> Specifies the IP address of the Security Gateway + for this client machine. + </t> + + <t hangText="KEY:"> Is the encoded RSA Public key of the Security + Gateway. The key is provided here to avoid a second DNS lookup. If this + field is absent, then a KEY resource record should be looked up in the + reverse-map of A.B.C.D. The key is transmitted in base64 format. + </t> + </list> + + <t> + The fields of the record MUST be separated by whitespace. This + MAY be: space, tab, newline, or carriage return. A space is preferred. + </t> + + <t> + In the case where Alice is located at a public address behind a + security gateway that has no fixed address (or no control over its + reverse-map), then Alice may delegate to a public key by domain name. + + <figure anchor="txtfqdnformat" + title="Format of reverse delegation record (FQDN version)"> + <artwork><![CDATA[ +X-IPsec-Server(P)=@FQDN KEY + ]]></artwork> + </figure> + </t> + + <list style="hanging"> + <t hangText="P:"> Is as above. + </t> + + <t hangText="FQDN:"> Specifies the FQDN that the Security Gateway + will identify itself with. + </t> + + <t hangText="KEY:"> Is the encoded RSA Public key of the Security + Gateway. </t> + </list> + + <t> + If there is more than one such TXT record with strongest (lowest + numbered) precedence, one Security Gateway is picked arbitrarily from + those specified in the strongest-preference records. + </t> + + <section title="Long TXT records"> + <t> + When packed into transport format, TXT records which are longer than 255 + characters are divided into smaller <character-strings>. + (See <xref target="RFC1035" /> section 3.3 and 3.3.14.) These MUST + be reassembled into a single string for processing. + Whitespace characters in the base64 encoding are to be ignored. + </t> + </section> + + <section title="Choice of TXT record"> + <t> + It has been suggested to use the KEY, OPT, CERT, or KX records + instead of a TXT record. None is satisfactory. + </t> + <t> The KEY RR has a protocol field which could be used to indicate a new protocol, +and an algorithm field which could be used to + indicate different contents in the key data. However, the KEY record + is clearly not intended for storing what are really authorizations, + it is just for identities. Other uses have been discouraged. + </t> + <t> OPT resource records, as defined in <xref target="RFC2671" /> are not + intended to be used for storage of information. They are not to be loaded, + cached or forwarded. They are, therefore, inappropriate for use here. + </t> + <t> + CERT records <xref target="RFC2538" /> can encode almost any set of + information. A custom type code could be used permitting any suitable + encoding to be stored, not just X.509. According to + the RFC, the certificate RRs are to be signed internally which may add undesirable +and unnecessary bulk. Larger DNS records may require TCP instead of UDP transfers. + </t> + <t> + At the time of protocol design, the CERT RR was not widely deployed and + could not be counted upon. Use of CERT records will be investigated, + and may be proposed in a future revision of this document. + </t> + <t> + KX records are ideally suited for use instead of TXT records, but had not been deployed at + the time of implementation. +<!-- Jakob Schlyter <j@crt.se> confirmed --> + </t> + </section> + </section> + + <section anchor="fqdn" title="Use of FQDN IDs"> + <t> + Unfortunately, not every administrator has control over the contents + of the reverse-map. Where the initiator (SG-A) has no suitable reverse-map, the + authorization record present in the reverse-map of Alice may refer to a + FQDN instead of an IP address. + </t> + <t> + In this case, the client's TXT record gives the fully qualified domain + name (FQDN) in place of its security gateway's IP address. + The initiator should use the ID_FQDN ID-payload in phase 1. + A forward lookup for a KEY record on the FQDN must yield the + initiator's public key. + </t> + <t> + This method can also be used when the external address of SG-A is + dynamic. + </t> + <t> + If SG-A is acting on behalf of Alice, then Alice must still delegate + authority for SG-A to do so in her reverse-map. When Alice and SG-A + are one and the same (i.e. Alice is acting as an end-node) then there + is no need for this when initiating only. </t> + <t>However, Alice must still delegate to herself if she wishes others to + initiate OE to her. See <xref target="txtfqdnformat" />. + </t> + < + </section> + +<section title="Key roll-over"> +<t> +Good cryptographic hygiene says that one should replace public/private key pairs +periodically. Some administrators may wish to do this as often as daily. Typical DNS +propagation delays are determined by the SOA Resource Record MINIMUM +parameter, which controls how long DNS replies may be cached. For reasonable +operation of DNS servers, administrators usually want this value to be at least several +hours, sometimes as a long as a day. This presents a problem - a new key MUST +not be used prior to it propagating through DNS. +</t> +<t> +This problem is dealt with by having the Security Gateway generate a new +public/private key pair at least MINIMUM seconds in advance of using it. It +then adds this key to the DNS (both as a second KEY record and in additional TXT +delegation records) at key generation time. Note: only one key is allowed in +each TXT record. +</t> +<t> +When authenticating, all gateways MUST have available all public keys +that are found in DNS for this entity. This permits the authenticating end +to check both the key for "today" and the key for "tomorrow". Note that it is +the end which is creating the signature (possesses the private key) that +determines which key is to be used. +</t> + + </section> +</section> + + +<section title="Network address translation interaction"> + <t> + There are no fundamentally new issues for implementing opportunistic encryption + in the presence of network address translation. Rather there are + only the regular IPsec issues with NAT traversal. + </t> + <t> + There are several situations to consider for NAT. + </t> + <section title="Co-located NAT/NAPT"> + <t> + If a security gateway is also performing network address translation on + behalf of an end-system, then the packet should be translated prior to + being subjected to opportunistic encryption. This is in contrast to + typically configured tunnels which often exist to bridge islands of + private network address space. The security gateway will use the translated source + address for phase 2, and so the responding security gateway will look up that address to + confirm SG-A's authorization. + </t> + <t> In the case of NAT (1:1), the address space into which the + translation is done MUST be globally unique, and control over the + reverse-map is assumed. + Placing of TXT records is possible. + </t> + <t> In the case of NAPT (m:1), the address will be the security + gateway itself. The ability to get + KEY and TXT records in place will again depend upon whether or not + there is administrative control over the reverse-map. This is + identical to situations involving a single host acting on behalf of + itself. + + FQDN style can be used to get around a lack of a reverse-map for + initiators only. + </t> + </section> + + <section title="Security Gateway behind NAT/NAPT"> + <t> + If there is a NAT or NAPT between the security gateways, then normal IPsec + NAT traversal problems occur. In addition to the transport problem + which may be solved by other mechanisms, there is the issue of + what phase 1 and phase 2 IDs to use. While FQDN could + be used during phase 1 for the security gateway, there is no appropriate ID for phase 2. + Due to the NAT, the end systems live in different IP address spaces. + </t> + </section> + + <section title="End System is behind a NAT/NAPT"> + <t> + If the end system is behind a NAT (perhaps SG-B), then there is, in fact, no way for + another end system to address a packet to this end system. + Not only is opportunistic encryption + impossible, but it is also impossible for any communication to + be initiate to the end system. It may be possible for this end + system to initiate in such communication. This creates an asymmetry, but this is common for + NAPT. + </t> + </section> +</section> + +<section title="Host implementations"> +<t> + When Alice and SG-A are components of the same system, they are + considered to be a host implementation. The packet sequence scenario remains unchanged. +</t> +<t> + Components marked Alice are the upper layers (TCP, UDP, the + application), and SG-A is the IP layer. +</t> +<t> + Note that tunnel mode is still required. +</t> +<t> + As Alice and SG-A are acting on behalf of themselves, no TXT based delegation + record is necessary for Alice to initiate. She can rely on FQDN in a + forward map. This is particularly attractive to mobile nodes such as + notebook computers at conferences. + To respond, Alice/SG-A will still need an entry in Alice's reverse-map. +</t> +</section> + +<section title="Multi-homing"> +<t> +If there are multiple paths between Alice and Bob (as illustrated in +the diagram with SG-D), then additional DNS records are required to establish +authorization. +</t> +<t> +In <xref target="networkdiagram" />, Alice has two ways to +exit her network: SG-A and SG-D. Previously SG-D has been ignored. Postulate +that there are routers between Alice and her set of security gateways +(denoted by the + signs and the marking of an autonomous system number for +Alice's network). Datagrams may, therefore, travel to either SG-A or SG-D en +route to Bob. +</t> +<t> +As long as all network connections are in good order, it does not matter how +datagrams exit Alice's network. When they reach either security gateway, the +security gateway will find the TXT delegation record in Bob's reverse-map, +and establish an SA with SG-B. +</t> +<t> +SG-B has no problem establishing that either of SG-A or SG-D may speak for +Alice, because Alice has published two equally weighted TXT delegation records: + <figure anchor="txtmultiexample" + title="Multiple gateway delegation example for Alice"> + <artwork><![CDATA[ +X-IPsec-Server(10)=192.1.1.5 AQMM...3s1Q== +X-IPsec-Server(10)=192.1.1.6 AAJN...j8r9== + ]]></artwork> + </figure> +</t> +<t> +Alice's routers can now do any kind of load sharing needed. Both SG-A and SG-D send datagrams addressed to Bob through +their tunnel to SG-B. +</t> +<t> +Alice's use of non-equal weight delegation records to show preference of one gateway over another, has relevance only when SG-B +is initiating to Alice. +</t> +<t> +If the precedences are the same, then SG-B has a more difficult time. It +must decide which of the two tunnels to use. SG-B has no information about +which link is less loaded, nor which security gateway has more cryptographic +resources available. SG-B, in fact, has no knowledge of whether both gateways +are even reachable. +</t> +<t> +The Public Internet's default-free zone may well know a good route to Alice, +but the datagrams that SG-B creates must be addressed to either SG-A or SG-D; +they can not be addressed to Alice directly. +</t> +<t> +SG-B may make a number of choices: +<list style="numbers"> +<t>It can ignore the problem and round robin among the tunnels. This + causes losses during times when one or the other security gateway is + unreachable. If this worries Alice, she can change the weights in her + TXT delegation records.</t> + +<t>It can send to the gateway from which it most recently received datagrams. + This assumes that routing and reachability are symmetrical.</t> + +<t>It can listen to BGP information from the Internet to decide which + system is currently up. This is clearly much more complicated, but if SG-B is already participating + in the BGP peering system to announce Bob, the results data may already + be available to it. </t> + +<t>It can refuse to negotiate the second tunnel. (It is unclear whether or +not this is even an option.)</t> + +<t>It can silently replace the outgoing portion of the first tunnel with the +second one while still retaining the incoming portions of both. SG-B can, +thus, accept datagrams from either SG-A or SG-D, but +send only to the gateway that most recently re-keyed with it.</t> +</list> +</t> + +<t> +Local policy determines which choice SG-B makes. Note that even if SG-B has perfect +knowledge about the reachability of SG-A and SG-D, Alice may not be reachable +from either of these security gateways because of internal reachability +issues. +</t> + +<t> +FreeS/WAN implements option 5. Implementing a different option is +being considered. The multi-homing aspects of OE are not well developed and may +be the subject of a future document. +</t> + +</section> + +<section title="Failure modes"> + <section title="DNS failures"> + <t> + If a DNS server fails to respond, local policy decides + whether or not to permit communication in the clear as embodied in + the connection classes in <xref target="initclasses" />. + It is easy to mount a denial of service attack on the DNS server + responsible for a particular network's reverse-map. + Such an attack may cause all communication with that network to go in + the clear if the policy is permissive, or fail completely + if the policy is paranoid. Please note that this is an active attack. + </t> + <t> + There are still many networks + that do not have properly configured reverse-maps. Further, if the policy is not to communicate, + the above denial of service attack isolates the target network. Therefore, the decision of whether +or not to permit communication in the clear MUST be a matter of local policy. + </t> + </section> + + <section title="DNS configured, IKE failures"> + <t> + DNS records claim that opportunistic encryption should + occur, but the target gateway either does not respond on port 500, or + refuses the proposal. This may be because of a crash or reboot, a + faulty configuration, or a firewall filtering port 500. + </t> + <t> + The receipt of ICMP port, host or network unreachable + messages indicates a potential problem, but MUST NOT cause communication + to fail + immediately. ICMP messages are easily forged by attackers. If such a + forgery caused immediate failure, then an active attacker could easily + prevent any + encryption from ever occurring, possibly preventing all communication. + </t> + <t> + In these situations a clear log should be produced + and local policy should dictate if communication is then + permitted in the clear. + </t> + </section> + + <section title="System reboots"> +<t> +Tunnels sometimes go down because the remote end crashes, +disconnects, or has a network link break. In general there is no +notification of this. Even in the event of a crash and successful reboot, +other SGs don't hear about it unless the rebooted SG has specific +reason to talk to them immediately. Over-quick response to temporary +network outages is undesirable. Note that a tunnel can be torn +down and then re-established without any effect visible to the user +except a pause in traffic. On the other hand, if one end reboots, +the other end can't get datagrams to it at all (except via +IKE) until the situation is noticed. So a bias toward quick +response is appropriate even at the cost of occasional +false alarms. +</t> + +<t> +A mechanism for recovery after reboot is a topic of current research and is not specified in this +document. +</t> + +<t> +A deliberate shutdown should include an attempt, using deletes, to notify all other SGs +currently connected by phase 1 SAs that communication is +about to fail. Again, a remote SG will assume this is a teardown. Attempts by the +remote SGs to negotiate new tunnels as replacements should be ignored. When possible, +SGs should attempt to preserve information about currently-connected SGs in non-volatile storage, so +that after a crash, an Initial-Contact can be sent to previous partners to +indicate loss of all previously established connections. +</t> + + </section> +</section> + +<!-- +<section title="Performance experiences"> + + Claudia> Is it useful to point out (or to clarify for our own discussion) any of the + Claudia> following: + + Claudia> * how much time this is likely to take on typical current hardware? + Claudia> * what steps are likely to be time consuming + Claudia> * how any added time could affect a typical transaction, such as hitting + Claudia> a web site + Claudia> * any ways to minimize such time delays + + <section title="Introduced latency"> + </section> + + <section title="Cryptographic performance"> + </section> + + <section title="Phase 1 SA performance"> + </section> + +</section> +--> + +<section title="Unresolved issues"> + <section title="Control of reverse DNS"> + <t> + The method of obtaining information by reverse DNS lookup causes + problems for people who cannot control their reverse DNS + bindings. This is an unresolved problem in this version, and is out + of scope. + </t> + </section> +</section> + +<section title="Examples"> + +<section title="Clear-text usage (permit policy)"> + +<t> +Two example scenarios follow. In the first example GW-A +(Gateway A) and GW-B (Gateway B) have always-clear-text policies, and in the second example they have an OE +policy. The clear-text policy serves as a reference for what occurs in +TCP/IP in the absence of Opportunistic Encryption. + +<t> +Alice wants to communicate with Bob. Perhaps she wants to retrieve a +web page from Bob's web server. In the absence of opportunistic +encryptors, the following events occur: +</t> + + <figure anchor="regulartiming" title="Timing of regular transaction"> + <artwork><![CDATA[ + Alice SG-A DNS SG-B Bob + Human or application + 'clicks' with a name. + (1) + + ------(2)--------------> + Application looks up + name in DNS to get + IP address. + + <-----(3)--------------- + Resolver returns "A" RR + to application with IP + address. + + (4) + Application starts a TCP session + or UDP session and OS sends + first datagram + + ----(5)-----> + Datagram is seen at first gateway + from Alice (SG-A). + + ----------(6)------> + Datagram traverses + network. + + ------(7)-----> + Datagram arrives + at Bob, is provided + to TCP. + + <------(8)------ + A reply is sent. + + <----------(9)------ + Datagram traverses + network. + <----(10)----- + Alice receives + answer. + + (11)-----------> + A second exchange + occurs. + ----------(12)-----> + --------------> + <--------------- + <------------------- + <------------- + ]]></artwork> +</figure> + +</t> +</section> + +<section title="Opportunistic encryption"> + +<t> +In the presence of properly configured opportunistic encryptors, the +event list is extended. Only changes are annotated. +</t> + +<t>The following symbols are used in the time-sequence diagram</t> + +<t> +<list style="hanging"> + <t hangText="-"> A single dash represents clear-text datagrams.</t> + <t hangText="="> An equals sign represents phase 2 (IPsec) cipher-text + datagrams.</t> + <t hangText="~"> A single tilde represents clear-text phase 1 datagrams.</t> + <t hangText="#"> A hash sign represents phase 1 (IKE) cipher-text + datagrams.</t> +</list> +</t> + +<t> +<figure anchor="opportunistictiming" title="Timing of opportunistic encryption transaction"> + <artwork><![CDATA[ + Alice SG-A DNS SG-B Bob + (1) + ------(2)--------------> + <-----(3)--------------- + (4)----(5)----->+ + SG-A sees datagram + to new target and + saves it as "first" + + ----(5B)-> + SG-A asks DNS + for TXT RR. + + <---(5C)-- + DNS returns TXT RR. + + ~~~~~~~~~~~~~(5D)~~~> + initial IKE main mode + packet is sent. + + <~~~~~~~~~~~~(5E1)~~~ + ~~~~~~~~~~~~~(5E2)~~> + <~~~~~~~~~~~~(5E3)~~~ + IKE phase 1 - privacy. + + #############(5E4)##> + SG-A sends ID to SG-B + <----(5F1)-- + SG-B asks DNS + for SG-A's public + KEY + -----(5F2)-> + DNS provides KEY RR. + SG-B authenticates SG-A + + <############(5E5)### + IKE phase 1 - complete + + #############(5G1)##> + IKE phase 2 - Alice<->Bob + tunnel is proposed. + + <----(5H1)-- + SG-B asks DNS for + Alice's TXT record. + -----(5H2)-> + DNS replies with TXT + record. SG-B checks + SG-A's authorization. + + <############(5G2)### + SG-B accepts proposal. + + #############(5G3)##> + SG-A confirms. + + ============(6)====> + SG-A sends "first" + packet in new IPsec + SA. + ------(7)-----> + packet is decrypted + and forward to Bob. + <------(8)------ + <==========(9)====== + return packet also + encrypted. + <-----(10)---- + + (11)-----------> + a second packet + is sent by Alice + ==========(12)=====> + existing tunnel is used + --------------> + <--------------- + <=================== + <------------- + ]]></artwork> +</figure> + +</t> + + <t> + For the purposes of this section, we will describe only the changes that + occur between <xref target="regulartiming" /> and + <xref target="opportunistictiming" />. This corresponds to time points 5, 6, 7, 9 and 10 on the list above. + </t> + +<list style="symbols"> + <t> + At point (5), SG-A intercepts the datagram because this source/destination pair lacks a policy +(the non-existent policy state). SG-A creates a hold policy, and buffers the datagram. SG-A requests keys from the keying daemon. + </t> + + <t> + SG-A's IKE daemon, having looked up the source/destination pair in the connection + class list, creates a new Potential OE connection instance. SG-A starts DNS + queries. + </t> + </section> + + <section title="(5C) DNS returns TXT record(s)"> + + <t> + DNS returns properly formed TXT delegation records, and SG-A's IKE daemon + causes this instance to make a transition from Potential OE connection to Pending OE + connection. + </t> + + <t> + Using the example above, the returned record might contain: + + <figure anchor="txtexample" + title="Example of reverse delegation record for Bob"> + <artwork><![CDATA[ +X-IPsec-Server(10)=192.1.1.5 AQMM...3s1Q== + ]]></artwork> + </figure> + with SG-B's IP address and public key listed. + </t> + + </section> + + <section title="(5D) Initial IKE main mode packet goes out"> + <t>Upon entering Pending OE connection, SG-A sends the initial ISAKMP + message with proposals. See <xref target="phase1id" />. + </t> + </section> + + <section title="(5E1) Message 2 of phase 1 exchange"> + <t> + SG-B receives the message. A new connection instance is created in the + unauthenticated OE peer state. + </t> + </section> + + <section title="(5E2) Message 3 of phase 1 exchange"> + <t> + SG-A sends a Diffie-Hellman exponent. This is an internal state of the + keying daemon. + </t> + </section> + + <section title="(5E3) Message 4 of phase 1 exchange"> + <t> + SG-B responds with a Diffie-Hellman exponent. This is an internal state of the + keying protocol. + </t> + </section> + + <section title="(5E4) Message 5 of phase 1 exchange"> + <t> + SG-A uses the phase 1 SA to send its identity under encryption. + The choice of identity is discussed in <xref target="phase1id" />. + This is an internal state of the keying protocol. + </t> + </section> + + <section title="(5F1) Responder lookup of initiator key"> + <t> + SG-B asks DNS for the public key of the initiator. + DNS looks for a KEY record by IP address in the reverse-map. + That is, a KEY resource record is queried for 4.1.1.192.in-addr.arpa + (recall that SG-A's external address is 192.1.1.4). + SG-B uses the resulting public key to authenticate the initiator. See <xref + target="KEY" /> for further details. + </t> + </section> + +<section title="(5F2) DNS replies with public key of initiator"> +<t> +Upon successfully authenticating the peer, the connection instance makes a +transition to authenticated OE peer on SG-B. +</t> +<t> +The format of the TXT record returned is described in +<xref target="TXT" />. +</t> +</section> + + <section title="(5E5) Responder replies with ID and authentication"> + <t> + SG-B sends its ID along with authentication material. This is an internal + state for the keying protocol. + </t> + </section> + + <section title="(5G) IKE phase 2"> + <section title="(5G1) Initiator proposes tunnel"> + <t> + Having established mutually agreeable authentications (via KEY) and + authorizations (via TXT), SG-A proposes to create an IPsec tunnel for + datagrams transiting from Alice to Bob. This tunnel is established only for + the Alice/Bob combination, not for any subnets that may be behind SG-A and SG-B. + </t> + </section> + + <section title="(5H1) Responder determines initiator's authority"> + <t> + While the identity of SG-A has been established, its authority to + speak for Alice has not yet been confirmed. SG-B does a reverse + lookup on Alice's address for a TXT record. + </t> + <t>Upon receiving this specific proposal, SG-B's connection instance + makes a transition into the potential OE connection state. SG-B may already have an + instance, and the check is made as described above.</t> + </section> + + <section title="(5H2) DNS replies with TXT record(s)"> + <t> + The returned key and IP address should match that of SG-A. + </t> + </section> + + <section title="(5G2) Responder agrees to proposal"> + <t> + Should additional communication occur between, for instance, Dave and Bob using + SG-A and SG-B, a new tunnel (phase 2 SA) would be established. The phase 1 SA + may be reusable. + </t> + <t>SG-A, having successfully keyed the tunnel, now makes a transition from + Pending OE connection to Keyed OE connection. + </t> + <t>The responder MUST setup the inbound IPsec SAs before sending its reply.</t> + </section> + + <section title="(5G3) Final acknowledgment from initiator"> + <t> + The initiator agrees with the responder's choice and sets up the tunnel. + The initiator sets up the inbound and outbound IPsec SAs. + </t> + <t> + The proper authorization returned with keys prompts SG-B to make a transition + to the keyed OE connection state. + </t> + <t>Upon receipt of this message, the responder may now setup the outbound + IPsec SAs.</t> + </section> + </section> + + <section title="(6) IPsec succeeds, and sets up tunnel for communication between Alice and Bob"> + <t> + SG-A sends the datagram saved at step (5) through the newly created + tunnel to SG-B, where it gets decrypted and forwarded. + Bob receives it at (7) and replies at (8). + </t> + </section> + + <section title="(9) SG-B already has tunnel up with G1 and uses it"> + <t> + At (9), SG-B has already established an SPD entry mapping Bob->Alice via a + tunnel, so this tunnel is simply applied. The datagram is encrypted to SG-A, + decrypted by SG-A and passed to Alice at (10). + </t> + + </section> +</section> <!-- OE example --> + +</section> <!-- Examples --> + +<section anchor="securityconsiderations" title="Security considerations"> + + <section title="Configured vs opportunistic tunnels"> +<t> + Configured tunnels are those which are setup using bilateral mechanisms: exchanging +public keys (raw RSA, DSA, PKIX), pre-shared secrets, or by referencing keys that +are in known places (distinguished name from LDAP, DNS). These keys are then used to +configure a specific tunnel. +</t> +<t> +A pre-configured tunnel may be on all the time, or may be keyed only when needed. +The end points of the tunnel are not necessarily static: many mobile +applications (road warrior) are considered to be configured tunnels. +</t> +<t> +The primary characteristic is that configured tunnels are assigned specific +security properties. They may be trusted in different ways relating to exceptions to +firewall rules, exceptions to NAT processing, and to bandwidth or other quality of service restrictions. +</t> +<t> +Opportunistic tunnels are not inherently trusted in any strong way. They are +created without prior arrangement. As the two parties are strangers, there +MUST be no confusion of datagrams that arrive from opportunistic peers and +those that arrive from configured tunnels. A security gateway MUST take care +that an opportunistic peer can not impersonate a configured peer. +</t> +<t> +Ingress filtering MUST be used to make sure that only datagrams authorized by +negotiation (and the concomitant authentication and authorization) are +accepted from a tunnel. This is to prevent one peer from impersonating another. +</t> +<t> +An implementation suggestion is to treat opportunistic tunnel +datagrams as if they arrive on a logical interface distinct from other +configured tunnels. As the number of opportunistic tunnels that may be +created automatically on a system is potentially very high, careful attention +to scaling should be taken into account. +</t> +<t> +As with any IKE negotiation, opportunistic encryption cannot be secure +without authentication. Opportunistic encryption relies on DNS for its +authentication information and, therefore, cannot be fully secure without +a secure DNS. Without secure DNS, opportunistic encryption can protect against passive +eavesdropping but not against active man-in-the-middle attacks. +</t> + </section> + + <section title="Firewalls versus Opportunistic Tunnels"> +<t> + Typical usage of per datagram access control lists is to implement various +kinds of security gateways. These are typically called "firewalls". +</t> +<t> + Typical usage of a virtual private network (VPN) within a firewall is to +bypass all or part of the access controls between two networks. Additional +trust (as outlined in the previous section) is given to datagrams that arrive +in the VPN. +</t> +<t> + Datagrams that arrive via opportunistically configured tunnels MUST not be +trusted. Any security policy that would apply to a datagram arriving in the +clear SHOULD also be applied to datagrams arriving opportunistically. +</t> + </section> + + <section title="Denial of service"> +<t> + There are several different forms of denial of service that an implementor + should concern themselves with. Most of these problems are shared with + security gateways that have large numbers of mobile peers (road warriors). +</t> +<t> + The design of ISAKMP/IKE, and its use of cookies, defend against many kinds + of denial of service. Opportunism changes the assumption that if the phase 1 (ISAKMP) + SA is authenticated, that it was worthwhile creating. Because the gateway will communicate with any machine, it is + possible to form phase 1 SAs with any machine on the Internet. +</t> + +</section> +</section> + +<section title="IANA Considerations"> +<t> + There are no known numbers which IANA will need to manage. +</t> +</section> + +<section title="Acknowledgments"> +<t> + Substantive portions of this document are based upon previous work by + Henry Spencer. +</t> +<t> + Thanks to Tero Kivinen, Sandy Harris, Wes Hardarker, Robert Moskowitz, + Jakob Schlyter, Bill Sommerfeld, John Gilmore and John Denker for their + comments and constructive criticism. +</t> +<t> + Sandra Hoffman and Bill Dickie did the detailed proof reading and editing. +</t> +</section> + +</middle> + +<back> +<references title="Normative references"> +<?rfc include="reference.OEspec" ?> +<!-- renumber according to reference order --> +<?rfc include="reference.RFC.0791" ?> +<?rfc include="reference.RFC.1009" ?> +<?rfc include="reference.RFC.1984" ?> +<?rfc include="reference.RFC.2119" ?> +<!-- IPsec --> +<?rfc include="reference.RFC.2367" ?> +<?rfc include="reference.RFC.2401" ?> +<?rfc include="reference.RFC.2407" ?> +<?rfc include="reference.RFC.2408" ?> +<?rfc include="reference.RFC.2409" ?> +<!-- MODPGROUPS --> +<?rfc include="reference.RFC.3526" ?> +<!-- DNSSEC --> +<?rfc include="reference.RFC.1034" ?> +<?rfc include="reference.RFC.1035" ?> +<?rfc include="reference.RFC.2671" ?> +<?rfc include="reference.RFC.1464" ?> +<?rfc include="reference.RFC.2535" ?> +<?rfc include="reference.RFC.3110" ?> +<?rfc include="reference.RFC.2538" ?> +<!-- COPS --> +<?rfc include="reference.RFC.2748" ?> +<!-- NAT --> +<?rfc include="reference.RFC.2663" ?> +</references> +<!-- <references title="Non-normative references"> --> +<!-- ESPUDP --> +<!-- <?rfc include="reference.ESPUDP" ?> --> +<!-- </references> --> +</back> +</rfc> +<!-- + $Id: draft-richardson-ipsec-opportunistic.xml,v 1.1 2004/03/15 20:35:24 as Exp $ + + $Log: draft-richardson-ipsec-opportunistic.xml,v $ + Revision 1.1 2004/03/15 20:35:24 as + added files from freeswan-2.04-x509-1.5.3 + + Revision 1.33 2003/06/30 03:19:59 mcr + timing-diagram with inline explanation. + + Revision 1.32 2003/06/30 01:57:44 mcr + initial edits per-Bob Braden. + + Revision 1.31 2003/05/26 19:31:23 mcr + updates to drafts - IPSEC RR - SC versions, and RFC3526 + reference in OE draft. + + Revision 1.30 2003/05/21 15:42:34 mcr + updates due to publication of RFC 3526. + + Revision 1.29 2003/01/17 16:22:55 mcr + rev 11 of OE draft. + + Revision 1.28 2002/07/25 19:27:31 mcr + added DHR's minor edits. + + Revision 1.27 2002/07/21 16:26:26 mcr + slides from presentation at OLS + draft-10 of OE draft. + + Revision 1.26 2002/07/16 03:46:53 mcr + second edits from Sandra. + + Revision 1.25 2002/07/16 03:36:14 mcr + removed HS from authors list + updated reference inclusion to use <?rfc-include directive. + Revision 1.24 2002/07/11 02:08:21 mcr + updated XML file from Sandra + + Revision 1.23 2002/06/06 17:18:53 mcr + spellcheck. + + Revision 1.22 2002/06/06 17:14:19 mcr + results of hand-editing session from May 28th. + This is FINAL OE draft. + + Revision 1.21 2002/06/06 02:25:44 mcr + results of hand-editing session from May 28th. + This is FINAL OE draft. + + Revision 1.20 2002/05/24 03:28:37 mcr + changes as requested by RFC editor. + + Revision 1.19 2002/04/09 16:01:05 mcr + comments from PHB. + + Revision 1.18 2002/04/08 02:14:34 mcr + RGBs changes to rev6. + + Revision 1.17 2002/03/12 21:23:55 mcr + adjusted definition of default-free zone. + moved text on key rollover from format description to new + section. + + Revision 1.16 2002/02/22 01:23:21 mcr + revisions from MCR (2002/2/18) and net. + + Revision 1.15 2002/02/21 20:44:12 mcr + extensive from DHR. + + Revision 1.14 2002/02/10 16:20:39 mcr + -05 draft. Many revisions to do "OE system in world of OE systems" + view of the universe. + + Revision 1.13 2001/12/20 04:35:22 mcr + fixed reference to rfc1984. + + Revision 1.12 2001/12/20 03:35:19 mcr + comments from Henry, Tero, and Sandy. + + Revision 1.11 2001/12/19 07:26:22 mcr + added comment about KX records. + + Revision 1.10 2001/11/09 04:28:10 mcr + fixed some typos with XML, and one s/SG-B/SG-D/. + + Revision 1.9 2001/11/09 04:07:13 mcr + expanded section 10: multihoming, with an example. + + Revision 1.8 2001/11/09 02:16:51 mcr + added lifetime/lifespan definitions. + moved example from 5B to 5C. + added reference to phase 1 IDs to 5D. + cleared up text in aging section. + added text about delegation of DNSSEC activity to a DNS server. + spelt out DH group names. + added text about ignoring TXT records unless DNSSEC is deployed (somerfeld) + added example of TXT delegation using FQDN. + clarified some text in NAT interaction section. + clarified absense of TXT record need for host implementation + + Revision 1.7 2001/11/08 23:09:37 mcr + changed revision of draft to 03. + + Revision 1.6 2001/11/08 19:37:14 mcr + fixed some formatting of Aging section. + + Revision 1.5 2001/11/08 19:19:30 mcr + fixed address for DHR, updated address for MCR, + added reference to original HS/DHR OE specification paper. + + Revision 1.4 2001/11/08 19:08:24 mcr + section 10, "Renewal and Teardown" added moved between 4/5, and + slightly rewritten. + + Revision 1.3 2001/11/08 18:56:34 mcr + sections 4.2, 5.6, 5.7.1 and 6.2 edited as per HS. + section 10, "Renewal and Teardown" added. + section 11, "Failure modes" completed. + + Revision 1.2 2001/11/05 20:31:31 mcr + added section from OE spec on aging and teardown. + + Revision 1.1 2001/11/05 04:27:58 mcr + OE draft added to documentation. + + Revision 1.12 2001/10/10 01:12:31 mcr + removed impact on DNS servers section. + removed nested comments. + adjusted data of issue + + Revision 1.11 2001/09/17 02:55:50 mcr + outline is now stable. + + Revision 1.5 2001/08/19 02:53:32 mcr + version 00d formatted. + + Revision 1.10 2001/08/19 02:34:04 mcr + version 00d formatted. + + Revision 1.9 2001/08/19 02:21:54 mcr + version 00d + + Revision 1.8 2001/07/20 19:07:06 mcr + commented out section 1.1 + + Revision 1.7 2001/07/20 14:14:22 mcr + HS and HD comments. + + Revision 1.6 2001/07/19 00:56:50 mcr + version 00b. + + Revision 1.5 2001/07/12 23:57:07 mcr + OE ID, 00. + + +!> diff --git a/doc/src/draft-richardson-ipsec-rr.html b/doc/src/draft-richardson-ipsec-rr.html new file mode 100644 index 000000000..08473104f --- /dev/null +++ b/doc/src/draft-richardson-ipsec-rr.html @@ -0,0 +1,659 @@ +<html><head><title>A method for storing IPsec keying material in DNS.</title> +<STYLE type='text/css'> + .title { color: #990000; font-size: 22px; line-height: 22px; font-weight: bold; text-align: right; + font-family: helvetica, arial, sans-serif } + .filename { color: #666666; font-size: 18px; line-height: 28px; font-weight: bold; text-align: right; + font-family: helvetica, arial, sans-serif } + p.copyright { color: #000000; font-size: 10px; + font-family: verdana, charcoal, helvetica, arial, sans-serif } + p { margin-left: 2em; margin-right: 2em; } + li { margin-left: 3em; } + ol { margin-left: 2em; margin-right: 2em; } + ul.text { margin-left: 2em; margin-right: 2em; } + pre { margin-left: 3em; color: #333333 } + ul.toc { color: #000000; line-height: 16px; + font-family: verdana, charcoal, helvetica, arial, sans-serif } + H3 { color: #333333; font-size: 16px; line-height: 16px; font-family: helvetica, arial, sans-serif } + H4 { color: #000000; font-size: 14px; font-family: helvetica, arial, sans-serif } + TD.header { color: #ffffff; font-size: 10px; font-family: arial, helvetica, san-serif; valign: top } + TD.author-text { color: #000000; font-size: 10px; + font-family: verdana, charcoal, helvetica, arial, sans-serif } + TD.author { color: #000000; font-weight: bold; margin-left: 4em; font-size: 10px; font-family: verdana, charcoal, helvetica, arial, sans-serif } + A:link { color: #990000; font-weight: bold; + font-family: MS Sans Serif, verdana, charcoal, helvetica, arial, sans-serif } + A:visited { color: #333333; font-weight: bold; + font-family: MS Sans Serif, verdana, charcoal, helvetica, arial, sans-serif } + A:name { color: #333333; font-weight: bold; + font-family: MS Sans Serif, verdana, charcoal, helvetica, arial, sans-serif } + .link2 { color:#ffffff; font-weight: bold; text-decoration: none; + font-family: monaco, charcoal, geneva, MS Sans Serif, helvetica, monotype, verdana, sans-serif; + font-size: 9px } + .RFC { color:#666666; font-weight: bold; text-decoration: none; + font-family: monaco, charcoal, geneva, MS Sans Serif, helvetica, monotype, verdana, sans-serif; + font-size: 9px } + .hotText { color:#ffffff; font-weight: normal; text-decoration: none; + font-family: charcoal, monaco, geneva, MS Sans Serif, helvetica, monotype, verdana, sans-serif; + font-size: 9px } +</style> +</head> +<body bgcolor="#ffffff" text="#000000" alink="#000000" vlink="#666666" link="#990000"> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<table width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table width="100%" border="0" cellpadding="2" cellspacing="1"> +<tr valign="top"><td width="33%" bgcolor="#666666" class="header">IPSECKEY WG</td><td width="33%" bgcolor="#666666" class="header">M. Richardson</td></tr> +<tr valign="top"><td width="33%" bgcolor="#666666" class="header">Internet-Draft</td><td width="33%" bgcolor="#666666" class="header">SSW</td></tr> +<tr valign="top"><td width="33%" bgcolor="#666666" class="header">Expires: March 4, 2004</td><td width="33%" bgcolor="#666666" class="header">September 4, 2003</td></tr> +</table></td></tr></table> +<div align="right"><font face="monaco, MS Sans Serif" color="#990000" size="+3"><b><br><span class="title">A method for storing IPsec keying material in DNS.</span></b></font></div> +<div align="right"><font face="monaco, MS Sans Serif" color="#666666" size="+2"><b><span class="filename">draft-ietf-ipseckey-rr-07.txt</span></b></font></div> +<font face="verdana, helvetica, arial, sans-serif" size="2"> + +<h3>Status of this Memo</h3> +<p> +This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.</p> +<p> +Internet-Drafts are working documents of the Internet Engineering +Task Force (IETF), its areas, and its working groups. +Note that other groups may also distribute working documents as +Internet-Drafts.</p> +<p> +Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any time. +It is inappropriate to use Internet-Drafts as reference material or to cite +them other than as "work in progress."</p> +<p> +The list of current Internet-Drafts can be accessed at +<a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p> +<p> +The list of Internet-Draft Shadow Directories can be accessed at +<a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p> +<p> +This Internet-Draft will expire on March 4, 2004.</p> + +<h3>Copyright Notice</h3> +<p> +Copyright (C) The Internet Society (2003). All Rights Reserved.</p> + +<h3>Abstract</h3> + +<p> +This document describes a new resource record for DNS. This record may be +used to store public keys for use in IPsec systems. + +</p> +<p> +This record replaces the functionality of the sub-type #1 of the KEY Resource +Record, which has been obsoleted by RFC3445. + +</p><a name="toc"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Table of Contents</h3> +<ul compact class="toc"> +<b><a href="#anchor1">1.</a> +Introduction<br></b> +<b><a href="#anchor2">1.1</a> +Overview<br></b> +<b><a href="#anchor3">1.2</a> +Usage Criteria<br></b> +<b><a href="#anchor4">2.</a> +Storage formats<br></b> +<b><a href="#anchor5">2.1</a> +IPSECKEY RDATA format<br></b> +<b><a href="#anchor6">2.2</a> +RDATA format - precedence<br></b> +<b><a href="#algotype">2.3</a> +RDATA format - algorithm type<br></b> +<b><a href="#gatewaytype">2.4</a> +RDATA format - gateway type<br></b> +<b><a href="#anchor7">2.5</a> +RDATA format - gateway<br></b> +<b><a href="#anchor8">2.6</a> +RDATA format - public keys<br></b> +<b><a href="#anchor9">3.</a> +Presentation formats<br></b> +<b><a href="#anchor10">3.1</a> +Representation of IPSECKEY RRs<br></b> +<b><a href="#anchor11">3.2</a> +Examples<br></b> +<b><a href="#anchor12">4.</a> +Security Considerations<br></b> +<b><a href="#anchor13">4.1</a> +Active attacks against unsecured IPSECKEY resource records<br></b> +<b><a href="#anchor14">5.</a> +IANA Considerations<br></b> +<b><a href="#anchor15">6.</a> +Acknowledgments<br></b> +<b><a href="#rfc.references1">§</a> +Normative references<br></b> +<b><a href="#rfc.references2">§</a> +Non-normative references<br></b> +<b><a href="#rfc.authors">§</a> +Author's Address<br></b> +<b><a href="#rfc.copyright">§</a> +Full Copyright Statement<br></b> +</ul> +<br clear="all"> + +<a name="anchor1"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.1"></a><h3>1. Introduction</h3> + +<p> + The type number for the IPSECKEY RR is TBD. + +</p> +<a name="rfc.section.1.1"></a><h4><a name="anchor2">1.1</a> Overview</h4> + +<p> + The IPSECKEY resource record (RR) is used to publish a public key that is + to be associated with a Domain Name System (DNS) name for use with the + IPsec protocol suite. This can be the public key of a host, + network, or application (in the case of per-port keying). + +</p> +<p> + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL + NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + RFC2119 <a href="#RFC2119">[8]</a>. + +</p> +<a name="rfc.section.1.2"></a><h4><a name="anchor3">1.2</a> Usage Criteria</h4> + +<p> + An IPSECKEY resource record SHOULD be used in combination with DNSSEC +unless some other means of authenticating the IPSECKEY resource record +is available. + +</p> +<p> + It is expected that there will often be multiple IPSECKEY resource + records at the same name. This will be due to the presence + of multiple gateways and the need to rollover keys. + + +</p> +<p> + This resource record is class independent. + +</p> +<a name="anchor4"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.2"></a><h3>2. Storage formats</h3> + +<a name="rfc.section.2.1"></a><h4><a name="anchor5">2.1</a> IPSECKEY RDATA format</h4> + +<p> + The RDATA for an IPSECKEY RR consists of a precedence value, a public key, + algorithm type, and an optional gateway address. + +</p></font><pre> + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | precedence | gateway type | algorithm | gateway | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------+ + + ~ gateway ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | / + / public key / + / / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| +</pre><font face="verdana, helvetica, arial, sans-serif" size="2"> + +<a name="rfc.section.2.2"></a><h4><a name="anchor6">2.2</a> RDATA format - precedence</h4> + +<p> +This is an 8-bit precedence for this record. This is interpreted in +the same way as the PREFERENCE field described in section +3.3.9 of RFC1035 <a href="#RFC1035">[2]</a>. + +</p> +<p> +Gateways listed in IPSECKEY records with lower precedence are +to be attempted first. Where there is a tie in precedence, the order +should be non-deterministic. + +</p> +<a name="rfc.section.2.3"></a><h4><a name="algotype">2.3</a> RDATA format - algorithm type</h4> + +<p> +The algorithm type field identifies the public key's cryptographic +algorithm and determines the format of the public key field. + +</p> +<p> +A value of 0 indicates that no key is present. + +</p> +<p> +The following values are defined: + +<blockquote class="text"><dl> +<dt>1</dt> +<dd>A DSA key is present, in the format defined in RFC2536 <a href="#RFC2536">[11]</a> +</dd> +<dt>2</dt> +<dd>A RSA key is present, in the format defined in RFC3110 <a href="#RFC3110">[12]</a> +</dd> +</dl></blockquote><p> +</p> +<a name="rfc.section.2.4"></a><h4><a name="gatewaytype">2.4</a> RDATA format - gateway type</h4> + +<p> +The gateway type field indicates the format of the information that +is stored in the gateway field. + +</p> +<p> +The following values are defined: + +<blockquote class="text"><dl> +<dt>0</dt> +<dd>No gateway is present +</dd> +<dt>1</dt> +<dd>A 4-byte IPv4 address is present +</dd> +<dt>2</dt> +<dd>A 16-byte IPv6 address is present +</dd> +<dt>3</dt> +<dd>A wire-encoded domain name is present. The wire-encoded +format is self-describing, so the length is implicit. The domain name +MUST NOT be compressed. +</dd> +</dl></blockquote><p> +</p> +<a name="rfc.section.2.5"></a><h4><a name="anchor7">2.5</a> RDATA format - gateway</h4> + +<p> +The gateway field indicates a gateway to which an IPsec tunnel may be +created in order to reach the entity named by this resource record. + +</p> +<p> +There are three formats: + +</p> +<p> +A 32-bit IPv4 address is present in the gateway field. The data +portion is an IPv4 address as described in section 3.4.1 of +<a href="#RFC1035">RFC1035</a>[2]. This is a 32-bit number in network byte order. + +</p> +<p>A 128-bit IPv6 address is present in the gateway field. +The data portion is an IPv6 address as described in section 2.2 of +<a href="#RFC1886">RFC1886</a>[7]. This is a 128-bit number in network byte order. + +</p> +<p> +The gateway field is a normal wire-encoded domain name, as described +in section 3.3 of RFC1035 <a href="#RFC1035">[2]</a>. Compression MUST NOT be used. + +</p> +<a name="rfc.section.2.6"></a><h4><a name="anchor8">2.6</a> RDATA format - public keys</h4> + +<p> +Both of the public key types defined in this document (RSA and DSA) +inherit their public key formats from the corresponding KEY RR formats. +Specifically, the public key field contains the algorithm-specific +portion of the KEY RR RDATA, which is all of the KEY RR DATA after the +first four octets. This is the same portion of the KEY RR that must be +specified by documents that define a DNSSEC algorithm. +Those documents also specify a message digest to be used for generation +of SIG RRs; that specification is not relevant for IPSECKEY RR. + +</p> +<p> +Future algorithms, if they are to be used by both DNSSEC (in the KEY +RR) and IPSECKEY, are likely to use the same public key encodings in +both records. Unless otherwise specified, the IPSECKEY public key +field will contain the algorithm-specific portion of the KEY RR RDATA +for the corresponding algorithm. The algorithm must still be +designated for use by IPSECKEY, and an IPSECKEY algorithm type number +(which might be different than the DNSSEC algorithm number) must be +assigned to it. + +</p> +<p>The DSA key format is defined in RFC2536 <a href="#RFC2536">[11]</a> +</p> +<p>The RSA key format is defined in RFC3110 <a href="#RFC3110">[12]</a>, +with the following changes: +</p> +<p> +The earlier definition of RSA/MD5 in RFC2065 limited the exponent and +modulus to 2552 bits in length. RFC3110 extended that limit to 4096 +bits for RSA/SHA1 keys. The IPSECKEY RR imposes no length limit on +RSA public keys, other than the 65535 octet limit imposed by the +two-octet length encoding. This length extension is applicable only +to IPSECKEY and not to KEY RRs. + +</p> +<a name="anchor9"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.3"></a><h3>3. Presentation formats</h3> + +<a name="rfc.section.3.1"></a><h4><a name="anchor10">3.1</a> Representation of IPSECKEY RRs</h4> + +<p> + IPSECKEY RRs may appear in a zone data master file. + The precedence, gateway type and algorithm and gateway fields are REQUIRED. + The base64 encoded public key block is OPTIONAL; if not present, + then the public key field of the resource record MUST be construed + as being zero octets in length. + +</p> +<p> + The algorithm field is an unsigned integer. No mnemonics are defined. + +</p> +<p> + If no gateway is to be indicated, then the gateway type field MUST + be zero, and the gateway field MUST be "." + +</p> +<p> + The Public Key field is represented as a Base64 encoding of the + Public Key. Whitespace is allowed within the Base64 text. For a + definition of Base64 encoding, see +<a href="#RFC1521">RFC1521</a>[3] Section 5.2. + +</p> +<p> + The general presentation for the record as as follows: +</p> +</font><pre> +IN IPSECKEY ( precedence gateway-type algorithm + gateway base64-encoded-public-key ) +</pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> + +</p> +<a name="rfc.section.3.2"></a><h4><a name="anchor11">3.2</a> Examples</h4> + +<p> +An example of a node 192.0.2.38 that will accept IPsec tunnels on its +own behalf. +</p> +</font><pre> +38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 1 2 + 192.0.2.38 + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +</pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> + +</p> +<p> +An example of a node, 192.0.2.38 that has published its key only. +</p> +</font><pre> +38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 0 2 + . + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +</pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> + +</p> +<p> +An example of a node, 192.0.2.38 that has delegated authority to the node +192.0.2.3. +</p> +</font><pre> +38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 1 2 + 192.0.2.3 + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +</pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> + +</p> +<p> +An example of a node, 192.0.1.38 that has delegated authority to the node +with the identity "mygateway.example.com". +</p> +</font><pre> +38.1.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 3 2 + mygateway.example.com. + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +</pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> + +</p> +<p> +An example of a node, 2001:0DB8:0200:1:210:f3ff:fe03:4d0 that has +delegated authority to the node 2001:0DB8:c000:0200:2::1 +</p> +</font><pre> +$ORIGIN 1.0.0.0.0.0.2.8.B.D.0.1.0.0.2.ip6.int. +0.d.4.0.3.0.e.f.f.f.3.f.0.1.2.0 7200 IN IPSECKEY ( 10 2 2 + 2001:0DB8:0:8002::2000:1 + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +</pre><font face="verdana, helvetica, arial, sans-serif" size="2"> +<p> + +</p> +<a name="anchor12"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.4"></a><h3>4. Security Considerations</h3> + +<p> + This entire memo pertains to the provision of public keying material + for use by key management protocols such as ISAKMP/IKE (RFC2407) + <a href="#RFC2407">[9]</a>. + +</p> +<p> +The IPSECKEY resource record contains information that SHOULD be +communicated to the end client in an integral fashion - i.e. free from +modification. The form of this channel is up to the consumer of the +data - there must be a trust relationship between the end consumer of this +resource record and the server. This relationship may be end-to-end +DNSSEC validation, a TSIG or SIG(0) channel to another secure source, +a secure local channel on the host, or some combination of the above. + +</p> +<p> +The keying material provided by the IPSECKEY resource record is not +sensitive to passive attacks. The keying material may be freely +disclosed to any party without any impact on the security properties +of the resulting IPsec session: IPsec and IKE provide for defense +against both active and passive attacks. + +</p> +<p> + Any user of this resource record MUST carefully document their trust + model, and why the trust model of DNSSEC is appropriate, if that is + the secure channel used. + +</p> +<a name="rfc.section.4.1"></a><h4><a name="anchor13">4.1</a> Active attacks against unsecured IPSECKEY resource records</h4> + +<p> +This section deals with active attacks against the DNS. These attacks +require that DNS requests and responses be intercepted and changed. +DNSSEC is designed to defend against attacks of this kind. + +</p> +<p> +The first kind of active attack is when the attacker replaces the +keying material with either a key under its control or with garbage. + +</p> +<p> +If the attacker is not able to mount a subsequent +man-in-the-middle attack on the IKE negotiation after replacing the +public key, then this will result in a denial of service, as the +authenticator used by IKE would fail. + +</p> +<p> +If the attacker is able to both to mount active attacks against DNS +and is also in a position to perform a man-in-the-middle attack on IKE and +IPsec negotiations, then the attacker will be in a position to compromise +the resulting IPsec channel. Note that an attacker must be able to +perform active DNS attacks on both sides of the IKE negotiation in +order for this to succeed. + +</p> +<p> +The second kind of active attack is one in which the attacker replaces +the the gateway address to point to a node under the attacker's +control. The attacker can then either replace the public key or remove +it, thus providing an IPSECKEY record of its own to match the +gateway address. + +</p> +<p> +This later form creates a simple man-in-the-middle since the attacker +can then create a second tunnel to the real destination. Note that, as before, +this requires that the attacker also mount an active attack against +the responder. + +</p> +<p> +Note that the man-in-the-middle can not just forward cleartext +packets to the original destination. While the destination may be +willing to speak in the clear, replying to the original sender, +the sender will have already created a policy expecting ciphertext. +Thus, the attacker will need to intercept traffic from both sides. In some +cases, the attacker may be able to accomplish the full intercept by use +of Network Addresss/Port Translation (NAT/NAPT) technology. + +</p> +<p> +Note that the danger here only applies to cases where the gateway +field of the IPSECKEY RR indicates a different entity than the owner +name of the IPSECKEY RR. In cases where the end-to-end integrity of +the IPSECKEY RR is suspect, the end client MUST restrict its use +of the IPSECKEY RR to cases where the RR owner name matches the +content of the gateway field. + +</p> +<a name="anchor14"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.5"></a><h3>5. IANA Considerations</h3> + +<p> +This document updates the IANA Registry for DNS Resource Record Types +by assigning type X to the IPSECKEY record. + +</p> +<p> +This document creates an IANA registry for the algorithm type field. + +</p> +<p> +Values 0, 1 and 2 are defined in <a href="#algotype">RDATA format - algorithm type</a>. Algorithm numbers +3 through 255 can be assigned by IETF Consensus (<a href="#RFC2434">see RFC2434</a>[6]). + +</p> +<p> +This document creates an IANA registry for the gateway type field. + +</p> +<p> +Values 0, 1, 2 and 3 are defined in <a href="#gatewaytype">RDATA format - gateway type</a>. +Algorithm numbers 4 through 255 can be assigned by +Standards Action (<a href="#RFC2434">see RFC2434</a>[6]). + +</p> +<a name="anchor15"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<a name="rfc.section.6"></a><h3>6. Acknowledgments</h3> + +<p> +My thanks to Paul Hoffman, Sam Weiler, Jean-Jacques Puig, Rob Austein, +and Olafur Gurmundsson who reviewed this document carefully. +Additional thanks to Olafur Gurmundsson for a reference implementation. + +</p> +<a name="rfc.references1"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Normative references</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><b><a name="RFC1034">[1]</a></b></td> +<td class="author-text">Mockapetris, P., "<a href="ftp://ftp.isi.edu/in-notes/rfc1034.txt">Domain names - concepts and facilities</a>", STD 13, RFC 1034, November 1987.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC1035">[2]</a></b></td> +<td class="author-text"><a href="mailto:">Mockapetris, P.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc1035.txt">Domain names - implementation and specification</a>", STD 13, RFC 1035, November 1987.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC1521">[3]</a></b></td> +<td class="author-text"><a href="mailto:nsb@bellcore.com">Borenstein, N.</a> and <a href="mailto:">N. Freed</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc1521.txt">MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies</a>", RFC 1521, September 1993.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2026">[4]</a></b></td> +<td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2026.txt">The Internet Standards Process -- Revision 3</a>", BCP 9, RFC 2026, October 1996.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2065">[5]</a></b></td> +<td class="author-text"><a href="mailto:dee@cybercash.com">Eastlake, D.</a> and <a href="mailto:charlie_kaufman@iris.com">C. Kaufman</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2065.txt">Domain Name System Security Extensions</a>", RFC 2065, January 1997.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2434">[6]</a></b></td> +<td class="author-text"><a href="mailto:narten@raleigh.ibm.com">Narten, T.</a> and <a href="mailto:Harald@Alvestrand.no">H. Alvestrand</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2434.txt">Guidelines for Writing an IANA Considerations Section in RFCs</a>", BCP 26, RFC 2434, October 1998.</td></tr> +</table> + +<a name="rfc.references2"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Non-normative references</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><b><a name="RFC1886">[7]</a></b></td> +<td class="author-text"><a href="mailto:set@thumper.bellcore.com">Thomson, S.</a> and <a href="mailto:Christian.Huitema@MIRSA.INRIA.FR">C. Huitema</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc1886.txt">DNS Extensions to support IP version 6</a>", RFC 1886, December 1995.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2119">[8]</a></b></td> +<td class="author-text"><a href="mailto:-">Bradner, S.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a>", BCP 14, RFC 2119, March 1997.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2407">[9]</a></b></td> +<td class="author-text"><a href="mailto:ddp@network-alchemy.com">Piper, D.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2407.txt">The Internet IP Security Domain of Interpretation for ISAKMP</a>", RFC 2407, November 1998.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2535">[10]</a></b></td> +<td class="author-text"><a href="mailto:dee3@us.ibm.com">Eastlake, D.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2535.txt">Domain Name System Security Extensions</a>", RFC 2535, March 1999.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC2536">[11]</a></b></td> +<td class="author-text"><a href="mailto:dee3@us.ibm.com">Eastlake, D.</a>, "<a href="ftp://ftp.isi.edu/in-notes/rfc2536.txt">DSA KEYs and SIGs in the Domain Name System (DNS)</a>", RFC 2536, March 1999.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC3110">[12]</a></b></td> +<td class="author-text">Eastlake, D., "<a href="ftp://ftp.isi.edu/in-notes/rfc3110.txt">RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)</a>", RFC 3110, May 2001.</td></tr> +<tr><td class="author-text" valign="top"><b><a name="RFC3445">[13]</a></b></td> +<td class="author-text">Massey, D. and S. Rose, "<a href="ftp://ftp.isi.edu/in-notes/rfc3445.txt">Limiting the Scope of the KEY Resource Record (RR)</a>", RFC 3445, December 2002.</td></tr> +</table> + +<a name="rfc.authors"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Author's Address</h3> +<table width="99%" border="0" cellpadding="0" cellspacing="0"> +<tr><td class="author-text"> </td> +<td class="author-text">Michael C. Richardson</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Sandelman Software Works</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">470 Dawson Avenue</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Ottawa, ON K1Z 5V7</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">CA</td></tr> +<tr><td class="author" align="right">EMail: </td> +<td class="author-text"><a href="mailto:mcr@sandelman.ottawa.on.ca">mcr@sandelman.ottawa.on.ca</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://www.sandelman.ottawa.on.ca/">http://www.sandelman.ottawa.on.ca/</a></td></tr> +</table> +<a name="rfc.copyright"><br><hr size="1" shade="0"></a> +<table border="0" cellpadding="0" cellspacing="2" width="30" height="15" align="right"><tr><td bgcolor="#990000" align="center" width="30" height="15"><a href="#toc" CLASS="link2"><font face="monaco, MS Sans Serif" color="#ffffff" size="1"><b> TOC </b></font></a><br></td></tr></table> +<h3>Full Copyright Statement</h3> +<p class='copyright'> +Copyright (C) The Internet Society (2003). All Rights Reserved.</p> +<p class='copyright'> +This document and translations of it may be copied and furnished to +others, and derivative works that comment on or otherwise explain it +or assist in its implementation may be prepared, copied, published and +distributed, in whole or in part, without restriction of any kind, +provided that the above copyright notice and this paragraph are +included on all such copies and derivative works. However, this +document itself may not be modified in any way, such as by removing +the copyright notice or references to the Internet Society or other +Internet organizations, except as needed for the purpose of +developing Internet standards in which case the procedures for +copyrights defined in the Internet Standards process must be +followed, or as required to translate it into languages other than +English.</p> +<p class='copyright'> +The limited permissions granted above are perpetual and will not be +revoked by the Internet Society or its successors or assigns.</p> +<p class='copyright'> +This document and the information contained herein is provided on an +"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING +TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING +BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION +HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF +MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p> +<h3>Acknowledgement</h3> +<p class='copyright'> +Funding for the RFC Editor function is currently provided by the +Internet Society.</p> +</font></body></html> diff --git a/doc/src/draft-richardson-ipsec-rr.xml b/doc/src/draft-richardson-ipsec-rr.xml new file mode 100644 index 000000000..e51b32615 --- /dev/null +++ b/doc/src/draft-richardson-ipsec-rr.xml @@ -0,0 +1,560 @@ +<?xml version="1.0"?> +<!DOCTYPE rfc SYSTEM "rfc2629.dtd"> +<?rfc toc="yes"?> + +<rfc ipr="full2026" docName="draft-ietf-ipseckey-rr-07.txt"> + +<front> + <area>Security</area> + <workgroup>IPSECKEY WG</workgroup> + <title abbrev="ipsecrr"> + A method for storing IPsec keying material in DNS. + </title> + + <author initials="M." surname="Richardson" fullname="Michael C. Richardson"> + <organization abbrev="SSW">Sandelman Software Works</organization> + <address> + <postal> + <street>470 Dawson Avenue</street> + <city>Ottawa</city> + <region>ON</region> + <code>K1Z 5V7</code> + <country>CA</country> + </postal> + <email>mcr@sandelman.ottawa.on.ca</email> + <uri>http://www.sandelman.ottawa.on.ca/</uri> + </address> + </author> + + <date month="September" year="2003" /> + +<abstract> + <t> +This document describes a new resource record for DNS. This record may be +used to store public keys for use in IPsec systems. +</t> + +<t> +This record replaces the functionality of the sub-type #1 of the KEY Resource +Record, which has been obsoleted by RFC3445. +</t> +</abstract> + +</front> + +<middle> + +<section title="Introduction"> +<t> + The type number for the IPSECKEY RR is TBD. +</t> + +<section title="Overview"> +<t> + The IPSECKEY resource record (RR) is used to publish a public key that is + to be associated with a Domain Name System (DNS) name for use with the + IPsec protocol suite. This can be the public key of a host, + network, or application (in the case of per-port keying). +</t> + +<t> + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL + NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + RFC2119 <xref target="RFC2119" />. +</t> +</section> + +<section title="Usage Criteria"> +<t> + An IPSECKEY resource record SHOULD be used in combination with DNSSEC +unless some other means of authenticating the IPSECKEY resource record +is available. +</t> + +<t> + It is expected that there will often be multiple IPSECKEY resource + records at the same name. This will be due to the presence + of multiple gateways and the need to rollover keys. + +</t> + +<t> + This resource record is class independent. +</t> +</section> +</section> + +<section title="Storage formats"> + +<section title="IPSECKEY RDATA format"> + +<t> + The RDATA for an IPSECKEY RR consists of a precedence value, a public key, + algorithm type, and an optional gateway address. +</t> + +<artwork><![CDATA[ + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | precedence | gateway type | algorithm | gateway | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------+ + + ~ gateway ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | / + / public key / + / / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| +]]></artwork> +</section> + +<section title="RDATA format - precedence"> +<t> +This is an 8-bit precedence for this record. This is interpreted in +the same way as the PREFERENCE field described in section +3.3.9 of RFC1035 <xref target="RFC1035" />. +</t> +<t> +Gateways listed in IPSECKEY records with lower precedence are +to be attempted first. Where there is a tie in precedence, the order +should be non-deterministic. +</t> +</section> + +<section anchor="algotype" title="RDATA format - algorithm type"> +<t> +The algorithm type field identifies the public key's cryptographic +algorithm and determines the format of the public key field. +</t> + +<t> +A value of 0 indicates that no key is present. +</t> + +<t> +The following values are defined: + <list style="hanging"> + <t hangText="1">A DSA key is present, in the format defined in RFC2536 <xref target="RFC2536" /></t> + <t hangText="2">A RSA key is present, in the format defined in RFC3110 <xref target="RFC3110" /></t> + </list> +</t> + +</section> + +<section anchor="gatewaytype" title="RDATA format - gateway type"> +<t> +The gateway type field indicates the format of the information that +is stored in the gateway field. +</t> + +<t> +The following values are defined: + <list style="hanging"> + <t hangText="0">No gateway is present</t> + <t hangText="1">A 4-byte IPv4 address is present</t> + <t hangText="2">A 16-byte IPv6 address is present</t> + <t hangText="3">A wire-encoded domain name is present. The wire-encoded +format is self-describing, so the length is implicit. The domain name +MUST NOT be compressed.</t> + </list> +</t> + +</section> + +<section title="RDATA format - gateway"> +<t> +The gateway field indicates a gateway to which an IPsec tunnel may be +created in order to reach the entity named by this resource record. +</t> +<t> +There are three formats: +</t> + +<t> +A 32-bit IPv4 address is present in the gateway field. The data +portion is an IPv4 address as described in section 3.4.1 of +<xref target="RFC1035">RFC1035</xref>. This is a 32-bit number in network byte order. +</t> + +<t>A 128-bit IPv6 address is present in the gateway field. +The data portion is an IPv6 address as described in section 2.2 of +<xref target="RFC1886">RFC1886</xref>. This is a 128-bit number in network byte order. +</t> + +<t> +The gateway field is a normal wire-encoded domain name, as described +in section 3.3 of RFC1035 <xref target="RFC1035" />. Compression MUST NOT be used. +</t> + +</section> + +<section title="RDATA format - public keys"> +<t> +Both of the public key types defined in this document (RSA and DSA) +inherit their public key formats from the corresponding KEY RR formats. +Specifically, the public key field contains the algorithm-specific +portion of the KEY RR RDATA, which is all of the KEY RR DATA after the +first four octets. This is the same portion of the KEY RR that must be +specified by documents that define a DNSSEC algorithm. +Those documents also specify a message digest to be used for generation +of SIG RRs; that specification is not relevant for IPSECKEY RR. +</t> + +<t> +Future algorithms, if they are to be used by both DNSSEC (in the KEY +RR) and IPSECKEY, are likely to use the same public key encodings in +both records. Unless otherwise specified, the IPSECKEY public key +field will contain the algorithm-specific portion of the KEY RR RDATA +for the corresponding algorithm. The algorithm must still be +designated for use by IPSECKEY, and an IPSECKEY algorithm type number +(which might be different than the DNSSEC algorithm number) must be +assigned to it. +</t> + +<t>The DSA key format is defined in RFC2536 <xref target="RFC2536" /></t>. + +<t>The RSA key format is defined in RFC3110 <xref target="RFC3110" />, +with the following changes:</t> + +<t> +The earlier definition of RSA/MD5 in RFC2065 limited the exponent and +modulus to 2552 bits in length. RFC3110 extended that limit to 4096 +bits for RSA/SHA1 keys. The IPSECKEY RR imposes no length limit on +RSA public keys, other than the 65535 octet limit imposed by the +two-octet length encoding. This length extension is applicable only +to IPSECKEY and not to KEY RRs. +</t> + +</section> + +</section> + + + +<section title="Presentation formats"> + +<section title="Representation of IPSECKEY RRs"> +<t> + IPSECKEY RRs may appear in a zone data master file. + The precedence, gateway type and algorithm and gateway fields are REQUIRED. + The base64 encoded public key block is OPTIONAL; if not present, + then the public key field of the resource record MUST be construed + as being zero octets in length. +</t> +<t> + The algorithm field is an unsigned integer. No mnemonics are defined. +</t> +<t> + If no gateway is to be indicated, then the gateway type field MUST + be zero, and the gateway field MUST be "." +</t> + +<t> + The Public Key field is represented as a Base64 encoding of the + Public Key. Whitespace is allowed within the Base64 text. For a + definition of Base64 encoding, see +<xref target="RFC1521">RFC1521</xref> Section 5.2. +</t> + + +<t> + The general presentation for the record as as follows: +<artwork><![CDATA[ +IN IPSECKEY ( precedence gateway-type algorithm + gateway base64-encoded-public-key ) +]]></artwork> +</t> +</section> + + +<section title="Examples"> +<t> +An example of a node 192.0.2.38 that will accept IPsec tunnels on its +own behalf. +<artwork><![CDATA[ +38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 1 2 + 192.0.2.38 + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +]]></artwork> +</t> + +<t> +An example of a node, 192.0.2.38 that has published its key only. +<artwork><![CDATA[ +38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 0 2 + . + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +]]></artwork> +</t> + +<t> +An example of a node, 192.0.2.38 that has delegated authority to the node +192.0.2.3. +<artwork><![CDATA[ +38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 1 2 + 192.0.2.3 + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +]]></artwork> +</t> + +<t> +An example of a node, 192.0.1.38 that has delegated authority to the node +with the identity "mygateway.example.com". +<artwork><![CDATA[ +38.1.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 3 2 + mygateway.example.com. + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +]]></artwork> +</t> + +<t> +An example of a node, 2001:0DB8:0200:1:210:f3ff:fe03:4d0 that has +delegated authority to the node 2001:0DB8:c000:0200:2::1 +<artwork><![CDATA[ +$ORIGIN 1.0.0.0.0.0.2.8.B.D.0.1.0.0.2.ip6.int. +0.d.4.0.3.0.e.f.f.f.3.f.0.1.2.0 7200 IN IPSECKEY ( 10 2 2 + 2001:0DB8:0:8002::2000:1 + AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) +]]></artwork> +</t> + +</section> +</section> + +<section title="Security Considerations"> +<t> + This entire memo pertains to the provision of public keying material + for use by key management protocols such as ISAKMP/IKE (RFC2407) + <xref target="RFC2407" />. +</t> + +<t> +The IPSECKEY resource record contains information that SHOULD be +communicated to the end client in an integral fashion - i.e. free from +modification. The form of this channel is up to the consumer of the +data - there must be a trust relationship between the end consumer of this +resource record and the server. This relationship may be end-to-end +DNSSEC validation, a TSIG or SIG(0) channel to another secure source, +a secure local channel on the host, or some combination of the above. +</t> + +<t> +The keying material provided by the IPSECKEY resource record is not +sensitive to passive attacks. The keying material may be freely +disclosed to any party without any impact on the security properties +of the resulting IPsec session: IPsec and IKE provide for defense +against both active and passive attacks. +</t> + +<t> + Any user of this resource record MUST carefully document their trust + model, and why the trust model of DNSSEC is appropriate, if that is + the secure channel used. +</t> + +<section title="Active attacks against unsecured IPSECKEY resource records"> +<t> +This section deals with active attacks against the DNS. These attacks +require that DNS requests and responses be intercepted and changed. +DNSSEC is designed to defend against attacks of this kind. +</t> + +<t> +The first kind of active attack is when the attacker replaces the +keying material with either a key under its control or with garbage. +</t> + +<t> +If the attacker is not able to mount a subsequent +man-in-the-middle attack on the IKE negotiation after replacing the +public key, then this will result in a denial of service, as the +authenticator used by IKE would fail. +</t> + +<t> +If the attacker is able to both to mount active attacks against DNS +and is also in a position to perform a man-in-the-middle attack on IKE and +IPsec negotiations, then the attacker will be in a position to compromise +the resulting IPsec channel. Note that an attacker must be able to +perform active DNS attacks on both sides of the IKE negotiation in +order for this to succeed. +</t> + +<t> +The second kind of active attack is one in which the attacker replaces +the the gateway address to point to a node under the attacker's +control. The attacker can then either replace the public key or remove +it, thus providing an IPSECKEY record of its own to match the +gateway address. +</t> + +<t> +This later form creates a simple man-in-the-middle since the attacker +can then create a second tunnel to the real destination. Note that, as before, +this requires that the attacker also mount an active attack against +the responder. +</t> + +<t> +Note that the man-in-the-middle can not just forward cleartext +packets to the original destination. While the destination may be +willing to speak in the clear, replying to the original sender, +the sender will have already created a policy expecting ciphertext. +Thus, the attacker will need to intercept traffic from both sides. In some +cases, the attacker may be able to accomplish the full intercept by use +of Network Addresss/Port Translation (NAT/NAPT) technology. +</t> + +<t> +Note that the danger here only applies to cases where the gateway +field of the IPSECKEY RR indicates a different entity than the owner +name of the IPSECKEY RR. In cases where the end-to-end integrity of +the IPSECKEY RR is suspect, the end client MUST restrict its use +of the IPSECKEY RR to cases where the RR owner name matches the +content of the gateway field. +</t> +</section> + +</section> + +<section title="IANA Considerations"> +<t> +This document updates the IANA Registry for DNS Resource Record Types +by assigning type X to the IPSECKEY record. +</t> + +<t> +This document creates an IANA registry for the algorithm type field. +</t> +<t> +Values 0, 1 and 2 are defined in <xref target="algotype" />. Algorithm numbers +3 through 255 can be assigned by IETF Consensus (<xref target="RFC2434">see RFC2434</xref>). +</t> + +<t> +This document creates an IANA registry for the gateway type field. +</t> +<t> +Values 0, 1, 2 and 3 are defined in <xref target="gatewaytype" />. +Algorithm numbers 4 through 255 can be assigned by +Standards Action (<xref target="RFC2434">see RFC2434</xref>). +</t> + + + +</section> + +<section title="Acknowledgments"> +<t> +My thanks to Paul Hoffman, Sam Weiler, Jean-Jacques Puig, Rob Austein, +and Olafur Gurmundsson who reviewed this document carefully. +Additional thanks to Olafur Gurmundsson for a reference implementation. +</t> +</section> + +</middle> + +<back> +<references title="Normative references"> +<!-- DNSSEC --> +<?rfc include="reference.RFC.1034" ?> +<?rfc include="reference.RFC.1035" ?> +<?rfc include="reference.RFC.1521" ?> +<?rfc include="reference.RFC.2026" ?> +<?rfc include="reference.RFC.2065" ?> +<?rfc include="reference.RFC.2434" ?> +</references> + +<references title="Non-normative references"> +<?rfc include="reference.RFC.1886" ?> +<?rfc include="reference.RFC.2119" ?> +<?rfc include="reference.RFC.2407" ?> +<?rfc include="reference.RFC.2535" ?> +<?rfc include="reference.RFC.2536" ?> +<?rfc include="reference.RFC.3110" ?> +<?rfc include="reference.RFC.3445" ?> +</references> +</back> +</rfc> +<!-- + $Id: draft-richardson-ipsec-rr.xml,v 1.1 2004/03/15 20:35:24 as Exp $ + + $Log: draft-richardson-ipsec-rr.xml,v $ + Revision 1.1 2004/03/15 20:35:24 as + added files from freeswan-2.04-x509-1.5.3 + + Revision 1.23 2003/09/04 23:26:09 mcr + more nits. + + Revision 1.22 2003/08/16 15:55:35 mcr + fixed version to -06. + + Revision 1.21 2003/08/16 15:52:32 mcr + Sam's comments on IANA considerations. + + Revision 1.20 2003/07/27 22:57:54 mcr + updated document with new text about a seperate registry + for the algorithm type. + + Revision 1.19 2003/06/30 01:51:50 mcr + minor typo fixes. + + Revision 1.18 2003/06/16 17:45:00 mcr + adjusted date on rev-04. + + Revision 1.17 2003/06/16 17:41:30 mcr + revision -04 + + Revision 1.16 2003/06/16 17:39:20 mcr + adjusted typos, and adjusted IANA considerations. + + Revision 1.15 2003/05/26 19:31:23 mcr + updates to drafts - IPSEC RR - SC versions, and RFC3526 + reference in OE draft. + + Revision 1.14 2003/05/23 13:57:40 mcr + updated draft ##. + + Revision 1.13 2003/05/23 13:54:45 mcr + updated month on draft. + + Revision 1.12 2003/05/21 15:42:49 mcr + new SC section with comments from Rob Austein. + + Revision 1.11 2003/05/20 20:52:22 mcr + new security considerations section. + + Revision 1.10 2003/05/20 19:07:47 mcr + rewrote Security Considerations. + + Revision 1.9 2003/05/20 18:17:09 mcr + nits from Rob Austein. + + Revision 1.8 2003/04/29 00:44:59 mcr + updates according to WG consensus: restored three-way + gateway field type. + + Revision 1.7 2003/03/30 17:00:29 mcr + updates according to community feedback. + + Revision 1.6 2003/03/19 02:20:24 mcr + updated draft based upon comments from working group + + Revision 1.5 2003/02/23 22:39:22 mcr + updates to IPSECKEY draft. + + Revision 1.4 2003/02/21 04:39:04 mcr + updated drafts, and added crosscompile.html + + Revision 1.3 2003/01/17 16:26:34 mcr + updated IPSEC KEY draft with restrictions. + + Revision 1.2 2002/08/26 18:20:54 mcr + updated documents + + Revision 1.1 2002/08/10 20:05:33 mcr + document proposing IPSECKEY Resource Record + + +!> diff --git a/doc/src/faq.html b/doc/src/faq.html new file mode 100644 index 000000000..f62fc1c88 --- /dev/null +++ b/doc/src/faq.html @@ -0,0 +1,2770 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN FAQ</title> + <meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, FAQ"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: faq.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1>FreeS/WAN FAQ</h1> + +<p>This is a collection of questions and answers, mostly taken from the +FreeS/WAN <a href="mail.html">mailing list</a>. See the project <a +href="http://www.freeswan.org/">web site</a> for more information. All the +FreeS/WAN documentation is online there.</p> + +<p>Contributions to the FAQ are welcome. Please send them to the project <a +href="mail.html">mailing list</a>.</p> +<hr> + +<h2><a name="questions">Index of FAQ questions</a></h2> +<ul> + <li><a href="#whatzit">What is FreeS/WAN?</a></li> + <li><a href="#problems">How do I report a problem or seek help?</a></li> + <li><a href="#generic">Can I get ...</a> + <ul> + <li><a href="#lemme_out">... an off-the-shelf system that includes + FreeS/WAN?</a></li> + <li><a href="#contractor">... contractors or staff who know + FreeS/WAN?</a></li> + <li><a href="#commercial">... commercial support?</a></li> + </ul> + </li> + <li><a href="#release">Release questions</a> + <ul> + <li><a href="#rel.current">What is the current release?</a></li> + <li><a href="#relwhen">When is the next release?</a></li> + <li><a href="#rel.bugs">Are there known bugs in the current + release?</a></li> + </ul> + </li> + <li><a href="mod_cons">Modifications and contributions</a> + <ul> + <li><a href="#modify.faq">Can I modify FreeS/WAN to ...?</a></li> + <li><a href="#contrib.faq">Can I contribute to the project?</a></li> + <li><a href="#ddoc.faq">Is there detailed design documentation?</a></li> + </ul> + </li> + <li><a href="#interact">Will FreeS/WAN work in my environment?</a> + <ul> + <li><a href="#interop.faq">Can FreeS/WAN talk to ... ?</a></li> + <li><a href="#old_to_new">Can different FreeS/WAN versions talk to each + other?</a></li> + <li><a href="#faq.bandwidth">Is there a limit on throughput?</a></li> + <li><a href="#faq.number">Is there a limit on number of + connections?</a></li> + <li><a href="#faq.speed">Is a ... fast enough to handle FreeS/WAN with + my loads?</a></li> + </ul> + </li> + <li><a href="#work_on">Will FreeS/WAN work on ...</a> + <ul> + <li><a href="#versions">... my version of Linux?</a></li> + <li><a href="#nonIntel.faq">... non-Intel CPUs?</a></li> + <li><a href="#multi.faq">... multiprocessors?</a></li> + <li><a href="#k.old">... an older kernel?</a></li> + <li><a href="#k.versions">... the latest kernel version?</a></li> + <li><a href="#interface.faq">... unusual network hardware?</a></li> + <li><a href="#vlan">... a VLAN (802.1q) network?</a></li> + </ul> + </li> + <li><a href="#features.faq">Does FreeS/WAN support ...</a> + <ul> + <li><a href="#VPN.faq">... site-to-site VPN applications</a></li> + <li><a href="#warrior.faq">... remote users connecting to a LAN</a></li> + <li><a href="#road.shared.possible">... remote users using shared + secret authentication?</a></li> + <li><a href="#wireless.faq">... wireless networks</a></li> + <li><a href="#PKIcert">... X.509 or other PKI certificates?</a></li> + <li><a href="#Radius">... user authentication (Radius, SecureID, + Smart Card ...)?</a></li> + <li><a href="#NATtraversal">... NAT traversal</a></li> + <li><a href="#virtID">... assigning a "virtual identity" to a remote + system?</a></li> + <li><a href="#noDES.faq">... single DES encryption?</a></li> + <li><a href="#AES.faq">... AES encryption?</a></li> + <li><a href="#other.cipher">... other encryption algorithms?</a></li> + </ul> + </li> + <li><a href="#canI">Can I ...</a> + <ul> + <li><a href="#policy.preconfig">...use policy groups along with + explicitly configured connections?</a></li> + <li><a href="#policy.off">...turn off policy groups?</a></li> +<!-- + <li><a href="#policy.otherinterface">...use policy groups + on an interface other than <VAR>%defaultroute</VAR>?</a></li> +--> + <li><a href="#reload">... reload connection info without + restarting?</a></li> + <li><a href="#masq.faq">... use several masqueraded subnets?</a></li> + <li><a href="#dup_route">... use subnets masqueraded to the same + addresses?</a></li> + <li><a href="#road.masq">... assign a road warrior an address on my net + (a virtual identity)?</a></li> + <li><a href="#road.many">... support many road warriors with one + gateway?</a></li> + <li><a href="#road.PSK">... have many road warriors using shared secret + authentication?</a></li> + <li><a href="#QoS">... use Quality of Service routing with + FreeS/WAN?</a></li> + <li><a href="#deadtunnel">... recognise dead tunnels and shut them + down?</a></li> + <li><a href="#demanddial">... build IPsec tunnels over a demand-dialed + link?</a></li> + <li><a href="#GRE">... build GRE, L2TP or PPTP tunnels over IPsec?</a></li> + <li><a href="#NetBIOS">... use Network Neighborhood (Samba, NetBIOS) over IPsec?</a></li> + </ul> + </li> + <li><a href="#setup.faq">Life's little mysteries</a> + <ul> + <li><a href="#cantping">I cannot ping ....</a></li> + <li><a href="#forever">It takes forever to ...</a></li> + <li><a href="#route">I send packets to the tunnel with route(8) but + they vanish</a></li> + <li><a href="#down_route">When a tunnel goes down, packets + vanish</a></li> + <li><a href="#firewall_ate">The firewall ate my packets!</a></li> + <li><a href="#dropconn">Dropped connections</a></li> + <li><a href="#defaultroutegone">Disappearing %defaultroute</a></li> + <li><a href="#tcpdump.faq">TCPdump on the gateway shows strange + things</a></li> + <li><a href="#no_trace">Traceroute does not show anything between the + gateways</a></li> + </ul> + </li> + <li><a href="#man4debug">Testing in stages (or .... works but ... + doesn't)</a> + <ul> + <li><a href="#nomanual">Manually keyed connections don't work</a></li> + <li><a href="#spi_error">One manual connection works, but second one + fails</a></li> + <li><a href="#man_no_auto">Manual connections work, but automatic + keying doesn't</a></li> + <li><a href="#nocomp">IPsec works, but connections using compression + fail</a></li> + <li><a href="#pmtu.broken">Small packets work, but large transfers + fail</a></li> + <li><a href="#subsub">Subnet-to-subnet works, but tests from the + gateways don't</a></li> + </ul> + </li> + <li><a href="#compile.faq">Compilation problems</a> + <ul> + <li><a href="#gmp.h_missing">gmp.h: No such file or directory</a></li> + <li><a href="#noVM">... virtual memory exhausted</a></li> + </ul> + </li> + <li><a href="#error">Interpreting error messages</a> + <ul> + <li><a href="#route-client">route-client (or host) exited with status + 7</a></li> + <li><a href="#unreachable">SIOCADDRT:Network is unreachable</a></li> + <li><a href="#modprobe">ipsec_setup: modprobe: Can't locate + moduleipsec</a></li> + <li><a href="#noKLIPS">ipsec_setup: Fatal error, kernel appears to lack + KLIPS</a></li> + <li><a href="#noDNS">ipsec_setup: ... failure to fetch key for ... from + DNS</a></li> + <li><a href="#dup_address">ipsec_setup: ... interfaces ... and ... + share address ...</a></li> + <li><a href="#kflags">ipsec_setup: Cannot adjust kernel flags</a></li> + <li><a href="#message_num">Message numbers (MI3, QR1, et cetera) in + Pluto messages</a></li> + <li><a href="#conn_name">Connection names in Pluto error + messages</a></li> + <li><a href="#cantorient">Pluto: ... can't orient connection</a></li> + <li><a href="#no.interface">... we have no ipsecN interface for either + end of this connection</a></li> + <li><a href="#noconn">Pluto: ... no connection is known</a></li> + <li><a href="#nosuit">Pluto: ... no suitable connection ...</a></li> + <li><a href="#noconn.auth">Pluto: ... no connection has been + authorized</a></li> + <li><a href="#noDESsupport">Pluto: ... OAKLEY_DES_CBC is not + supported.</a></li> + <li><a href="#notransform">Pluto: ... no acceptable transform</a></li> + <li><a href="#rsasigkey">rsasigkey dumps core</a></li> + <li><a href="#sig4">!Pluto failure!: ... exited with ... signal + 4</a></li> + <li><a href="#econnrefused">ECONNREFUSED error message</a></li> + <li><a href="#no_eroute">klips_debug: ... no eroute!</a></li> + <li><a href="#SAused">... trouble writing to /dev/ipsec ... SA already + in use</a></li> + <li><a href="#ignore">... ignoring ... payload</a></li> + <li><a href="#unknown_rightcert">unknown parameter name "rightcert"</a></li> + </ul> + <li><a href="#spam">Why don't you restrict the mailing lists to reduce + spam?</a></li> +</ul> +<hr> + +<h2><a name="whatzit">What is FreeS/WAN?</a></h2> + +<p>FreeS/WAN is a Linux implementation of the <a +href="glossary.html#IPSEC">IPsec</a> protocols, providing security services +at the IP (Internet Protocol) level of the network.</p> + +<p>For more detail, see our <a href="intro.html">introduction</a> document or +the FreeS/WAN project <a href="http://www.freeswan.org/">web site</a>.</p> + +<p>To start setting it up, go to our <a href="quickstart.html">quickstart +guide</a>.</p> + +<p>Our <a href="web.html">web links</a> document has information on <a +href="web.html#implement">IPsec for other systems</a>.</p> + +<h2><a name="problems">How do I report a problem or seek help?</a></h2> + +<DL> +<DT>Read our <a href="trouble.html">troubleshooting</a> document.</DT> +<DD><p>It may guide you to a solution. If not, see its +<a href="trouble.html#prob.report">problem reporting</a> section.</p> + +<p>Basically, what it says is <strong>give us the output from <var>ipsec +barf</var> from both gateways</strong>. Without full information, we cannot +diagnose a problem. However, <var>ipsec barf</var> produces a lot of output. +If at all possible, <strong>please make barfs accessible via the web or +FTP</strong> rather than sending enormous mail messages.</p> +</DD> + +<DT><strong>Use the <a href="mail.html">users mailing list</a> for problem +reports</strong>, rather than mailing developers directly. +</DT> + +<DD> +<ul> + <li>This gives you access to more expertise, including users who may have + encountered and solved the same problems.</li> + <li>It is more likely to get a quick response. Developers may get behind on + email, or even ignore it entirely for a while, but a list message (given + a reasonable Subject: line) is certain to be read by a fair number of + people within hours.</li> + <li>It may also be important because of <a + href="politics.html#exlaw">cryptography export laws</a>. A US citizen who + provides technical assistance to foreign cryptographic work might be + charged under the arms export regulations. Such a charge would be easier + to defend if the discussion took place on a public mailing list than if + it were done in private mail.</li> +</ul> +</DD> + +<DT>Try irc.freenode.net#freeswan.</DT> + +<DD> +<p>FreeS/WAN developers, volunteers and users can often be found there. +Be patient and be +prepared to provide lots of information to support your question.</p> + +<p>If your question was really interesting, and you found an answer, +please share that with the class by posting to the +<a href="mail.html">users mailing list</a>. That way others with the +same problem can find your answer in the archives.</p> +</DD> + +<DT>Premium support is also available.</DT> +<DD> +<p>See the next several questions.</p> +</DD> +</DL> + +<h2><a name="generic">Can I get ...</a></h2> + +<h3><a name="lemme_out">Can I get an off-the-shelf system that includes +FreeS/WAN?</a></h3> + +<p>There are a number of Linux distributions or firewall products which +include FreeS/WAN. See this <a href="intro.html#products">list</a>. Using one +of these, chosen to match your requirements and budget, may save you +considerable time and effort.</p> + +<p>If you don't know your requirements, start by reading Schneier's <a +href="biblio.html#secrets">Secrets and Lies</a>. That gives the best overview +of security issues I have seen. Then consider hiring a consultant (see next +question) to help define your requirements.</p> + +<h3><a name="consultant">Can I hire consultants or staff who know +FreeS/WAN?</a></h3> + +<p>If you want the help of a contractor, or to hire staff with FreeS/WAN +expertise, you could:</p> +<ul> + <li>check availability in your area through your local Linux User Group (<a + href="http://lugww.counter.li.org/">LUG Index</a>)</li> + <li>try asking on our <a href="mail.html">mailing list</a></li> +</ul> + +<p>For companies offerring support, see the next question.</p> + +<h3><a name="commercial">Can I get commercial support?</a></h3> + +<p>Many of the distributions or firewall products which include FreeS/WAN +(see this <a href="intro.html#products">list</a>) come with commercial +support or have it available as an option.</p> + +<p>Various companies specialize in commercial support of open source +software. Our project leader was a founder of the first such company, Cygnus +Support. It has since been bought by <a +href="http://www.redhat.com">Redhat</a>. Another such firm is <a +href="http://www.linuxcare.com">Linuxcare</a>.</p> + +<h2><a name="release">Release questions</a></h2> + +<h3><a name="rel.current">What is the current release?</a></h3> + +<p>The current release is the highest-numbered tarball on our <a +href="ftp://ftp.xs4all.nl/pub/crypto/freeswan">distribution site</a>. Almost +always, any of <a href="intro.html#mirrors">the mirrors</a> will have the +same file, though perhaps not for a day or so after a release.</p> + +<p>Unfortunately, the web site is not always updated as quickly as it should +be.</p> + +<h3><a name="relwhen">When is the next release?</a></h3> + +<p>We try to do a release approximately every six to eight weeks. +</p> + +<p>If pre-release tests fail and the fix appears complex, or more generally +if the code does not appear stable when a release is scheduled, we will just +skip that release.</p> + +<p>For serious bugs, we may bring out an extra bug-fix release. These get +numbers in the normal release series. For example, there was a bug found in +FreeS/WAN 1.6, so we did another release less than two weeks later. The +bug-fix release was called 1.7.</p> + +<h3><a name="rel.bugs">Are there known bugs in the current release?</a></h3> + +<p>Any problems we are aware of at the time of a release are documented in +the <a href="../BUGS">BUGS</a> file for that release. You should also look at +the <a href="../CHANGES">CHANGES</a> file.</p> + +<p>Bugs discovered after a release are discussed on the <a +href="mail.html">mailing lists</a>. The easiest way to check for any problems +in the current code would be to peruse the +<a href="http://lists.freeswan.org/pipermail/briefs">List In Brief</a>.</p> + +<h2><a name="mod_cons">Modifications and contributions</a></h2> + +<h3><a name="modify.faq">Can I modify FreeS/WAN to ...?</a></h3> + +<p>You are free to modify FreeS/WAN in any way. See the discussion of <a +href="intro.html#licensing">licensing</a> in our introduction document.</p> + +<p>Before investing much energy in any such project, we suggest that you</p> +<ul> + <li>check the list of <a href="web.html#patch">existing patches</a></li> + <li>post something about your project to the <a href="mail.html">design + mailing list</a></li> +</ul> + +<p>This may prevent duplicated effort, or lead to interesting +collaborations.</p> + +<h3><a name="contrib.faq">Can I contribute to the project?</a></h3> +In general, we welcome contributions from the community. Various contributed +patches, either to fix bugs or to add features, have been incorporated into +our distribution. Other patches, not yet included in the distribution, are +listed in our <a href="web.html#patch">web links</a> section. + +<p>Users have also contributed heavily to documentation, both by creating +their own <a href="intro.html#howto">HowTos</a> and by posting things on the +<a href="mail.html">mailing lists</a> which I have quoted in these HTML +docs.</p> + +<p>There are, however, some caveats.</p> + +<p>FreeS/WAN is being implemented in Canada, by Canadians, largely to ensure +that is it is entirely free of export restrictions. See this <a +href="politics.html#status">discussion</a>. We <strong>cannot accept code +contributions from US residents or citizens</strong>, not even one-line bugs +fixes. The reasons for this were recently discussed extensively on the +mailing list, in a thread starting <a +href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/01/msg00111.html">here</a>.</p> + +<p>Not all contributions are of interest to us. The project has a set of +fairly ambitious and quite specific goals, described in our <a +href="intro.html#goals">introduction</a>. Contributions that lead toward +these goals are likely to be welcomed enthusiastically. Other contributions +may be seen as lower priority, or even as a distraction.</p> + +<p>Discussion of possible contributions takes place on the <a +href="mail.html">design mailing list</a>.</p> + +<h3><a name="ddoc.faq">Is there detailed design documentation?</a></h3> +There are: +<ul> + <li><a href="rfc.html">RFCs</a> specifying the protocols we implement</li> + <li><a href="manpages.html">man pages</a> for our utilities, library + functions and file formats</li> + <li>comments in the source code</li> + <li><a href="index.html">HTML documentation</a> written primarily for + users</li> + <li>archived discussions from the <a href="mail.html">mailing lists</a></li> + <li>other papers mentioned in our <a + href="intro.html#applied">introduction</a></li> +</ul> + +<p>The only formal design documents are a few papers in the last category +above. All the other categories, however, have things to say about design as +well.</p> + +<h2><a name="interact">Will FreeS/WAN work in my environment?</a></h2> + +<h3><a name="interop.faq">Can FreeS/WAN talk to ...?</a></h3> + +<p>The IPsec protocols are designed to support interoperation. In theory, any +two IPsec implementations should be able to talk to each other. In practice, +it is considerably more complex. We have a whole <a +href="interop.html">interoperation document</a> devoted to this problem.</p> + +<p>An important part of that document is links to the many <a +href="interop.html#otherpub">user-written HowTos</a> on interoperation +between FreeS/WAN and various other implementations. Often the users know +more than the developers about these issues (and almost always more than me +:-), so these documents may be your best resource.</p> + +<h3><a name="old_to_new">Can different FreeS/WAN versions talk to each +other?</a></h3> + +<p>Linux FreeS/WAN can interoperate with many IPsec implementations, +including earlier versions of Linux FreeS/WAN itself.</p> + +<p>In a few cases, there are some complications. See our <a +href="interop.html#oldswan">interoperation</a> document for details.</p> + +<h3><a name="faq.bandwidth">Is there a limit on throughput?</a></h3> + +<p>There is no hard limit, but see below.</p> + +<h3><a name="faq.number">Is there a limit on number of tunnels?</a></h3> + +<p>There is no hard limit, but see next question.</p> + +<h3><a name="faq.speed">Is a ... fast enough to handle FreeS/WAN with my +loads?</a></h3> + +<p>A quick summary:</p> +<dl> + <dt>Even a limited machine can be useful</dt> + <dd>A 486 can handle a T1, ADSL or cable link, though the machine may be + breathing hard.</dd> + <dt>A mid-range PC (say 800 MHz with good network cards) can do a lot of + IPsec</dt> + <dd>With up to roughly 50 tunnels and aggregate bandwidth of 20 Megabits + per second, it willl have cycles left over for other tasks.</dd> + <dt>There are limits</dt> + <dd>Even a high end CPU will not come close to handling a fully loaded + 100 Mbit/second Ethernet link. + <p>Beyond about 50 tunnels it needs careful management.</p> + </dd> +</dl> + +<p>See our <a href="performance.html">FreeS/WAN performance</a> document for +details.</p> + +<h2><a name="work_on">Will FreeS/WAN work on ... ?</a></h2> + +<h3><a name="versions">Will FreeS/WAN run on my version of Linux?</a></h3> + +<p>We build and test on Redhat distributions, but FreeS/WAN runs just fine on +several other distributions, sometimes with minor fiddles to adapt to the +local environment. Details are in our <a +href="compat.html#otherdist">compatibility</a> document. Also, some +distributions or products come with <a href="intro.html#products">FreeS/WAN +included</a>.</p> + +<h3><a name="nonIntel.faq">Will FreeS/WAN run on non-Intel CPUs?</a></h3> + +<p>FreeS/WAN is <strong>intended to run on all CPUs Linux supports</strong>. +We know of it being used in production on x86, ARM, Alpha and MIPS. It has +also had successful tests on PPC and SPARC, though we don't know of actual +use there. Details are in our <a href="compat.html#CPUs">compatibility</a> +document.</p> + +<h3><a name="multi.faq">Will FreeS/WAN run on multiprocessors?</a></h3> + +<p>FreeS/WAN is designed to work on any SMP architecture Linux supports, and +has been tested successfully on at least dual processor Intel architecture +machines. Details are in our <a +href="compat.html#multiprocessor">compatibility</a> document.</p> + +<h3><a name="k.old">Will FreeS/WAN work on an older kernel?</a></h3> + +<p>It might, but we strongly recommend using a recent 2.2 or 2.4 series +kernel. Sometimes the newer versions include security fixes which can be +quite important on a gateway.</p> + +<p>Also, we use recent kernels for development and testing, so those are +better tested and, if you do encounter a problem, more easily supported. If +something breaks applying recent FreeS/WAN patches to an older kernel, then +"update your kernel" is almost certain to be the first thing we suggest. It +may be the only suggestion we have.</p> + +<p>The precise kernel versions supported by a particular FreeS/WAN release +are given in the <a href="XX">README</a> file of that release.</p> + +<p>See the following question for more on kernels.</p> + +<h3><a name="k.versions">Will FreeS/WAN run on the latest kernel +version?</a></h3> + +<p>Sometimes yes, but quite often, no.</p> + +<p>Kernel versions supported are given in the <a href="../README">README</a> +file of each FreeS/WAN release. Typically, they are whatever production +kernels were current at the time of our release (or shortly before; we might +release for kernel <var>n</var> just as Linus releases <var>n+1</var>). Often +FreeS/WAN will work on slightly later kernels as well, but of course this +cannot be guaranteed.</p> + +<p>For example, FreeS/WAN 1.91 was released for kernels 2.2.19 or 2.4.5, the +current kernels at the time. It also worked on 2.4.6, 2.4.7 and 2.4.8, but +2.4.9 had changes that caused compilation errors if it was patched with +FreeS/WAN 1.91.</p> + +<p>When such changes appear, we put a fix in the FreeS/WAN snapshots, and +distribute it with our next release. However, this is not a high priority for +us, and it may take anything from a few days to several weeks for such a +problem to find its way to the top of our kernel programmer's To-Do list. In +the meanwhile, you have two choices:</p> +<ul> + <li>either stick with a slightly older kernel, even if it is not the latest + and greatest. This is recommended for production systems; new versions + may have new bugs.</li> + <li>or fix the problem yourself and send us a patch, via the <a + href="mail.html">Users mailing list</a>.</li> +</ul> + +<p>We don't even try to keep up with kernel changes outside the main 2.2 and +2.4 branches, such as the 2.4.x-ac patched versions from Alan Cox or the 2.5 +series of development kernels. We'd rather work on developing the FreeS/WAN +code than on chasing these moving targets. We are, however, happy to get +patches for problems discovered there.</p> + +<p>See also the <a href="install.html#choosek">Choosing a kernel</a> section +of our installation document.</p> + +<h3><a name="interface.faq">Will FreeS/WAN work on unusual network +hardware?</a></h3> + +<p>IPsec is designed to work over any network that IP works over, and +FreeS/WAN is intended to work over any network interface hardware that Linux +supports.</p> + +<p>If you have working IP on some unusual interface -- perhaps Arcnet, Token +Ring, ATM or Gigabit Ethernet -- then IPsec should "just work".</p> + +<p>That said, practice is sometimes less tractable than theory. Our testing +is done almost entirely on:</p> +<ul> + <li>10 or 100 Mbit Ethernet</li> + <li>ADSL or cable connections, with and without PPPoE</li> + <li>IEEE 802.11 wireless LANs (see <a href="#wireless.faq">below</a>)</li> +</ul> + +<p>If you have some other interface, especially an uncommon one, it is +entirely possible you will get bitten either by a FreeS/WAN bug which our +testing did not turn up, or by a bug in the driver that shows up only with +our loads.</p> + +<p>If IP works on your interface and FreeS/WAN doesn't, seek help on the <a +href="mail.html">mailing lists</a>.</p> + +<p>Another FAQ section describes <a href="#pmtu.broken">MTU problems</a>. +These are a possibility for some interfaces.</p> + +<h3><a name="vlan">Will FreeS/WAN work on a VLAN (802.1q) network?</a></h3> + +<p> + Yes, FreeSwan works fine, though some network drivers have problems + with jumbo sized ethernet frames. If you used interfaces=%defaultroute + you do not need to change anything, but if you specified an interface + (eg eth0) then remember you must change that to reflect the VLAN + interface (eg eth0.2 for VLAN ID 2). +</p> +<p> + The "eepro100" module is known to be broken, use the e100 driver + for those cards instead (included in 2.4 as 'alternative driver' for + the Intel EtherExpressPro/100. +</p> +<p> + You do not need to change any MTU setting (those are workarounds + that are only needed for buggy drivers) +</p> + +<p><em>This FAQ contributed by Paul Wouters.</em></p> + +<h2><a name="features.faq">Does FreeS/WAN support ...</a></h2> + +<p>For a discussion of which parts of the IPsec specifications FreeS/WAN does +and does not implement, see our <a href="compat.html#spec">compatibility</a> +document.</p> + +<p>For information on some often-requested features, see below.</p> + +<h3><a name="VPN.faq"></a>Does FreeS/WAN support site-to-site VPN +(<A HREF="glossary.html#VPN">Virtual Private Network</A>) +applications?</h3> + +<p>Absolutely. See this FreeS/WAN-FreeS/WAN +<A HREF="config.html">configuration example</A>. +If only one site is using FreeS/WAN, there may be a relevant HOWTO on our +<A HREF="interop.html">interop page</A>. +</p> + +<h3><a name="warrior.faq">Does FreeS/WAN support remote users connecting to a +LAN?</a></h3> + +<p>Yes. We call the remote users "Road Warriors". Check out our +FreeS/WAN-FreeS/WAN +<A HREF="config.html#config.rw">Road Warrior Configuration Example</A>.</P> + +<p>If your Road Warrior is a Windows or Mac PC, you may need to +install an IPsec implementation on that machine. +Our <A HREF="interop.html">interop</A> page lists many available brands, +and features links to several HOWTOs. + + +<h3><a name="road.shared.possible">Does FreeS/WAN support remote users using +shared secret authentication?</a></h3> + +<p><strong>Yes, but</strong> there are severe restrictions, so <strong>we +strongly recommend using </strong><a +href="glossary.html#RSA"><strong>RSA</strong></a><strong> keys for +</strong> <a +href="glossary.html#authentication"><strong>authentication</strong></a> +<strong> +instead</strong>.</p> + +<p>See this <a href="#road.PSK">FAQ question</a>.</p> + +<h3><a name="wireless.faq">Does FreeS/WAN support wireless networks?</a></h3> + +<p>Yes, it is a common practice to use IPsec over wireless networks because +their built-in encryption, <a href="glossary.html#WEP">WEP</a>, is +insecure.</p> + +<p>There is some <a href="adv_config.html#wireless.config">discussion</a> in +our advanced configuration document. See also the +<A HREF="http://www.wavesec.org">WaveSEC site</A>.</p> + +<h3><a name="PKIcert">Does FreeS/WAN support X.509 or other PKI +certificates?</a></h3> + +<P>Vanilla FreeS/WAN does not support X.509, but Andreas Steffen +and others have provided a popular, well-supported X.509 patch.</P> + +<UL> +<LI><A HREF="http://www.strongsec.com/freeswan">patch</A> +</LI> +<LI><A HREF="http://www.freeswan.ca">Super FreeS/WAN</A> incorporates +this and other user-contributed patches. +</LI> +<LI> +Kai Martius' <A HREF="http://www.strongsec.com/freeswan/install.htm">X.509 +Installation and Configuration Guide</A> +</LI> +</UL> + +<P> +Linux FreeS/WAN features +<A HREF="quickstart.html">Opportunistic Encryption</A>, an alternative +Public Key Infrastructure based on Secure DNS. +</P> + +<h3><a name="Radius">Does FreeS/WAN support user authentication (Radius, +SecureID, Smart Card...)?</a></h3> + +<P>Andreas Steffen's <A HREF="http://www.strongsec.com/freeswan">X.509 patch</A> (v. 1.42+) supports Smart Cards. The patch +does not ship with vanilla FreeS/WAN, but will be incorporated into +<A HREF="http://www.freeswan.ca/">Super FreeS/WAN +2.01+</A>. The patch implements the PCKS#15 +Cryptographic Token Information Format Standard, using the OpenSC smartcard +library functions.</P> + +<P>Older news:</P> + +<P>A user-supported patch to FreeS/WAN 1.3, for smart card style +authentication, is available on +<A HREF="http://alcatraz.webcriminals.com/~bastiaan/ipsec">Bastiaan's site</A>. +It supports skeyid and ibutton. +This patch is not part of Super FreeS/WAN.</p> + +<p>For a while progress on this front was impeded by a lack of standard. +The IETF <a +href="http://www.ietf.org/html.charters/ipsra-charter.html">working group</a> +has now nearly completed its recommended solution to the problem; meanwhile +several vendors have implemented various things.</p> + +<!-- +<p>The <a href="web.html#patch">patches</a> section of our web links document +has links to some user work on this.</p> +--> + +<p>Of course, there are various ways to avoid any requirement for user +authentication in IPsec. Consider the situation where road warriors build +IPsec tunnels to your office net and you are considering requiring user +authentication during tunnel negotiation. Alternatives include:</p> +<ul> + <li>If you can trust the road warrior machines, then set them up so that + only authorised users can create tunnels. If your road warriors use + laptops, consider the possibility of theft.</li> + <li>If the tunnel only provides access to particular servers and you can + trust those servers, then set the servers up to require user + authentication.</li> +</ul> + +<p>If either of those is trustworthy, it is not clear that you need user +authentication in IPsec.</p> + + +<h3><a name="NATtraversal">Does FreeS/WAN support NAT traversal?</a></h3> + +<p>Vanilla FreeS/WAN does not, but thanks to Mathieu Lafon and +Arkoon Network Security, there's a patch to support this.</P> + +<UL> +<LI><A HREF="http://open-source.arkoon.net">patch and documentation</A> +</LI> +<LI><A HREF="http://www.freeswan.ca">Super FreeS/WAN</A> incorporates +this and other user-contributed patches. +</LI> +</UL> + +<P>The NAT traversal patch has some issues with PSKs, so you may wish to +authenticate with RSA keys, or X.509 (requires a patch which is also +included in Super FreeS/WAN). Doing the latter also has +advantages when dealing with large numbers of clients who may be behind NAT; +instead of having to make an individual Roadwarrior connection for each +virtual IP, you can use the "rightsubnetwithin" parameter to specify a range. +See +<A HREF="http://www.strongsec.com/freeswan/install.htm#section_4.4">these +<VAR>rightsubnetwithin</VAR> instructions</A>. +</P> + + +<h3><a name="virtID">Does FreeS/WAN support assigning a "virtual identity" to +a remote system?</a></h3> + +<p>Some IPsec implementations allow you to make the source address on packets +sent by a Road Warrior machine be something other than the address of its +interface to the Internet. This is sometimes described as assigning a virtual +identity to that machine.</p> + +<p>FreeS/WAN does not directly support this, but it can be done. See this <a +href="#road.masq">FAQ question</a>.</p> + +<h3><a name="noDES.faq">Does FreeS/WAN support single DES encryption?</a></h3> + +<p><strong>No</strong>, single DES is not used either at the <a +href="glossary.html#IKE">IKE</a> level for negotiating connections or at the +<a href="glossary.html#IPsec">IPsec</a> level for actually building them.</p> + +<p>Single DES is <a href="politics.html#desnotsecure">insecure</a>. As we see +it, it is more important to deliver real security than to comply with a +standard which has been subverted into allowing use of inadequate methods. +See this <a href="politics.html#weak">discussion</a>.</p> + +<p>If you want to interoperate with an IPsec implementation which offers only +DES, see our <a href="interop.html#noDES">interoperation</a> document.</p> + +<h3><a name="AES.faq">Does FreeS/WAN support AES encryption?</a></h3> + +<p><a href="glossary.html#AES">AES</a> is a new US government <a +href="glossary.html#block">block cipher</a> standard to replace the obsolete +<a href="glossary.html#DES">DES</a>.</p> + +<p>At time of writing (March 2002), the FreeS/WAN distribution does not yet +support AES but user-written <a href="web.html#patch">patches</a> are +available to add it. Our kernel programmer is working on integrating those +patches into the distribution, and there is active discussion of this on the +design mailimg list.</p> + +<h3><a name="other.cipher">Does FreeS/WAN support other encryption +algorithms?</a></h3> + +<p>Currently <a href="glossary.html#3DES">triple DES</a> is the only cipher +supported. AES will almost certainly be added (see previous question), and it +is likely that in the process we will also add the other two AES finalists +with open licensing, Twofish and Serpent.</p> + +<p>We are extremely reluctant to add other ciphers. This would make both use +and maintenance of FreeS/WAN more complex without providing any clear +benefit. Complexity is emphatically not desirable in a security product.</p> + +<p>Various users have written patches to add other ciphers. We provide <a +href="web.html#patch">links</a> to these.</p> + +<h2><a name="canI">Can I ...</a></h2> + + +<h3><a name="policy.preconfig">Can I use policy groups along with +explicitly configured connections?</a></h3> + +<p>Yes, you can, so long as you pay attention to the selection rule, +which can be summarized "the most specific +connection wins". We describe the rule in our +<A HREF="policygroups.html#policy.group.notes">policy groups</A> document, +and provide a more technical explanation in +<A HREF="manpage.d/ipsec.conf.5.html">man ipsec.conf</A>. +</p> + +<p>A good guideline: If you have a regular connection defined in +<VAR>ipsec.conf</VAR>, ensure that a subset of that connection +is not listed in a less restrictive policy group. Otherwise, +FreeS/WAN will use the subset, with its more specific source/destination +pair.</p> + +<p>Here's an example. Suppose you are the system administrator at 192.0.2.2. +You have this connection in ipsec.conf: +<VAR>ipsec.conf</VAR>: + +<PRE>conn net-to-net + left=192.0.2.2 # you are here + right=192.0.2.8 + rightsubnet=192.0.2.96/27 + .... +</PRE> + +<p>If you then place a host or net within <VAR>rightsubnet</VAR>, +(let's say 192.0.2.98) in <VAR>private-or-clear</VAR>, you may find +that 192.0.2.2 at times communicates in the +clear with 192.0.2.98. That's consistent with the rule, but may be +contrary to your expectations.</p> + +<p>On the other hand, it's safe to put a larger subnet in a less +restrictive policy group file. If <VAR>private-or-clear</VAR> +contains 192.0.2.0/24, then the more specific <VAR>net-to-net</VAR> +connection is used for any communication to 192.0.2.96/27. The +more general policy applies only to communication with hosts or subnets in +192.0.2.0/24 without a more specific policy or connection.</p> + + +<h3><a name="policy.off">Can I turn off policy groups?</a></h3> + +<p>Yes. Use <A HREF="policygroups.html#disable_policygroups">these +instructions</A>.</p> + +<!-- +<h3><a name="policy.otherinterface">Can I use policy groups + on an interface other than <VAR>%defaultroute</VAR>?</a></h3> + +<p>??<p> +--> + +<h3><a name="reload">Can I reload connection info without restarting?</a></h3> + +<p>Yes, you can do this. Here are the details, in a mailing list message from +Pluto programmer Hugh Redelmeier:</p> +<pre>| How can I reload config's without restarting all of pluto and klips? I am using +| FreeSWAN -> PGPNet in a medium sized production environment, and would like to be +| able to add new connections ( i am using include config/* ) without dropping current +| SA's. +| +| Can this be done? +| +| If not, are there plans to add this kind of feature? + + ipsec auto --add whatever +This will look in the usual place (/etc/ipsec.conf) for a conn named +whatever and add it. + +If you added new secrets, you need to do + ipsec auto --rereadsecrets +before Pluto needs to know those secrets. + +| I have looked (perhaps not thoroughly enough tho) to see how to do this: + +There may be more bits to look for, depending on what you are trying +to do.</pre> + +<p>Another useful command here is <var>ipsec auto --replace +<conn_name></var> which re-reads data for a named connection.</p> + +<h3><a name="masq.faq">Can I use several masqueraded subnets?</a></h3> + +<p>Yes. This is done all the time. See the discussion in our <a +href="config.html#route_or_not">setup</a> document. The only restriction is +that the subnets on the two ends must not overlap. See the next question.</p> + +<p>Here is a mailing list message on the topic. The user incorrectly thinks +you need a 2.4 kernel for this -- actually various people have been doing it +on 2.0 and 2.2 for quite some time -- but he has it right for 2.4.</p> +<pre>Subject: Double NAT and freeswan working :) + Date: Sun, 11 Mar 2001 + From: Paul Wouters <paul@xtdnet.nl> + +Just to share my pleasure, and make an entry for people who are searching +the net on how to do this. Here's the very simple solution to have a double +NAT'ed network working with freeswan. (Not sure if this is old news, but I'm +not on the list (too much spam) and I didn't read this in any HOWTO/FAQ/doc +on the freeswan site yet (Sandy, put it in! :) + +10.0.0.0/24 --- 10.0.0.1 a.b.c.d ---- a.b.c.e {internet} ----+ + | +10.0.1.0/24 --- 10.0.1.1 f.g.h.i ---- f.g.h.j {internet} ----+ + +the goal is to have the first network do a VPN to the second one, yet also +have NAT in place for connections not destinated for the other side of the +NAT. Here the two Linux security gateways have one real IP number (cable +modem, dialup, whatever. + +The problem with NAT is you don't want packets from 10.*.*.* to 10.*.*.* +to be NAT'ed. While with Linux 2.2, you can't, with Linux 2.4 you can. + +(This has been tested and works for 2.4.2 with Freeswan snapshot2001mar8b) + +relevant parts of /etc/ipsec.conf: + + left=f.g.h.i + leftsubnet=10.0.1.0/24 + leftnexthop=f.g.h.j + leftfirewall=yes + leftid=@firewall.netone.nl + leftrsasigkey=0x0........ + right=a.b.c.d + rightsubnet=10.0.0.0/24 + rightnexthop=a.b.c.e + rightfirewall=yes + rightid=@firewall.nettwo.nl + rightrsasigkey=0x0...... + # To authorize this connection, but not actually start it, at startup, + # uncomment this. + auto=add + +and now the real trick. Setup the NAT correctly on both sites: + +iptables -t nat -F +iptables -t nat -A POSTROUTING -o eth0 -d \! 10.0.0.0/8 -j MASQUERADE + +This tells the NAT code to only do NAT for packets with destination other then +10.* networks. note the backslash to mask the exclamation mark to protect it +against the shell. + +Happy painting :) + +Paul</pre> + +<h3><a name="dup_route">Can I use subnets masqueraded to the same +addresses?</a></h3> + +<p><strong>No.</strong> The notion that IP addresses are unique is one of the +fundamental principles of the IP protocol. Messing with it is exceedingly +perilous.</p> + +<p>Fairly often a situation comes up where a company has several branches, +all using the same <a href="glossary.html#non-routable">non-routable +addresses</a>, perhaps 192.168.0.0/24. This works fine as long as those nets +are kept distinct. The <a href="glossary.html#masq">IP masquerading</a> on +their firewalls ensures that packets reaching the Internet carry the firewall +address, not the private address.</p> + +<p>This can break down when IPsec enters the picture. FreeS/WAN builds a +tunnel that pokes through both masquerades and delivers packets from +<var>leftsubnet</var> to <var>rightsubnet</var> and vice versa. For this to +work, the two subnets <em>must</em> be distinct.</p> + +<p>There are several solutions to this problem.</p> + +<p>Usually, you <strong>re-number the subnets</strong>. Perhaps the Vancouver +office becomes 192.168.101.0/24, Calgary 192.168.102.0/24 and so on. +FreeS/WAN can happily handle this. With, for example +<var>leftsubnet=192.168.101.0/24</var> and +<var>rightsubnet=192.168.102.0/24</var> in a connection description, any +machine in Calgary can talk to any machine in Vancouver. If you want to be +more restrictive and use something like +<var>leftsubnet=192.168.101.128/25</var> and +<var>rightsubnet=192.168.102.240/28</var> so only certain machines on each +end have access to the tunnel, that's fine too.</p> + +<p>You could also <strong>split the subnet</strong> into smaller ones, for +example using <var>192.168.1.0/25</var> in Vancouver and +<var>rightsubnet=192.168.0.128/25</var> in Calgary.</p> + +<p>Alternately, you can just <strong>give up routing</strong> directly to +machines on the subnets. Omit the <var>leftsubnet</var> and +<var>rightsubnet</var> parameters from your connection descriptions. Your +IPsec tunnels will then run between the public interfaces of the two +firewalls. Packets will be masqueraded both before they are put into tunnels +and after they emerge. Your Vancouver client machines will see only one +Calgary machine, the firewall.</p> + +<h3><a name="road.masq">Can I assign a road warrior an address on my net (a +virtual identity)?</a></h3> + +<p>Often it would be convenient to be able to give a Road Warrior an IP +address which appears to be on the local network. Some IPsec implementations +have support for this, sometimes calling the feature "virtual identity".</p> + +<p>Currently (Sept 2002) FreeS/WAN does not support this, and we have +no definite plans to add it. The difficulty is that is not yet a standard +mechanism for it. There is an Internet Draft for a method of doing it using +<a href="#DHCP">DHCP</a> which looks promising. FreeS/WAN may support that in +a future release.</p> + +<p>In the meanwhile, you can do it yourself using the Linux iproute2(8) +facilities. Details are in <a +href="http://www.av8n.com/vpn/iproute2.htm">this +paper</a>.</p> + +<p>Another method has also been discussed on the mailing list.:</p> +<ul> + <li>You can use a variant of the <a + href="adv_config.html#extruded.config">extruded subnet</a> procedure.</li> + <li>You have to avoid having the road warrior's assigned address within the + range you actually use at home base. See previous question.</li> + <li>On the other hand, you want the roadwarrior's address to be within the + range that <em>seems</em> to be on your network.</li> +</ul> + +<p>For example, you might have:</p> +<dl> + <dt>leftsubnet=a.b.c.0/25</dt> + <dd>head office network</dd> + <dt>rightsubnet=a.b.c.129/32</dt> + <dd>extruded to a road warrior. Note that this is not in a.b.c.0/25</dd> + <dt>a.b.c.0/24</dt> + <dd>whole network, including both the above</dd> +</dl> + +<p>You then set up routing so that the office machines use the IPsec gateway +as their route to a.b.c.128/25. The leftsubnet parameter tells the road +warriors to use tunnels to reach a.b.c.0/25, so you should have two-way +communication. Depending or your network and applications, there may be some +additional work to do on DNS or Windows configuration</p> + +<h3><a name="road.many">Can I support many road warriors with one +gateway?</a></h3> + +<p>Yes. This is easily done, using</p> +<dl> + <dt>either RSA authentication</dt> + <dd>standard in the FreeS/WAN distribution</dd> + <dt>or X.509 certificates</dt> + <dd>requires <a href="#PKIcert">Super FreeS/WAN or a patch</a>.</dd> +</dl> + +<p>In either case, each Road Warrior must have a different key or +certificate.</p> + +<p>It is also possible using pre-shared key authentication, +though we don't recommend this; see the +<a href="#road.PSK">next question</a> for details.</p> + +<p>If you expect to have more than a few dozen Road Warriors connecting +simultaneously, you may need a fairly powerful gateway machine. See our +document on <a href="performance.html">FreeS/WAN performance</a>.</p> + +<h3><a name="road.PSK">Can I have many road warriors using shared secret +authentication?</a></h3> + +<p><STRONG>Yes, but avoid it if possible</STRONG>.</p> + +<p>You can have multiple Road Warriors using shared secret authentication +<strong>only if they all use the same secret</strong>. You must also +set:<p> + +<PRE> uniqueids=no </PRE> + +<p>in the connection definition.</p> + + +<p>Why it's less secure:</p> +<ul> + <li>If you have many users, it becomes almost certain the secret will + leak</li> + <li>The secret becomes quite valuable to an attacker</li> + <li>All users authenticate the same way, so the gateway cannot tell them + apart for logging or access control purposes</li> + <li>Changing the secret is difficult. You have to securely notify all + users.</li> + <li>If you find out the secret has been compromised, you can change it, but + then what? None of your users can connect without the new secret. How + will you notify them all, quickly and securely, without using the + VPN?</li> +</ul> + +<p>This is a designed-in limitation of the <a +href="glossary.html#IKE">IKE</a> key negotiation protocol, not a problem with +our implementation.</p> + +<p><strong>We very strongly recommend that you avoid using shared secret +authentication for multiple Road Warriors.</strong> Use RSA authentication +instead.</p> + +<p>The longer story: When using shared secrets, the protocol requires +that the responding +gateway be able to determine which secret to use at a time when all it knows +about the initiator is an IP address. This works fine if you know the +initiator's address in advance and can use it to look up the appropiriate +secret. However, it fails for Road Warriors since the gateway cannot know +their IP addresses in advance.</p> + +<p>With RSA signatures (or certificates) the protocol is slightly different. +The initiator provides an identifier early in the exchange and the responder +can use that identifier to look up the correct key or certificate. See <a +href="#road.many">above</a>.</p> + +<h3><a name="QoS">Can I use Quality of Service routing with +FreeS/WAN?</a></h3> + +<p>From project technical lead Henry Spencer:</p> +<pre>> Do QoS add to FreeS/WAN? +> For example integrating DiffServ and FreeS/WAN? + +With a current version of FreeS/WAN, you will have to add hidetos=no to +the config-setup section of your configuration file. By default, the TOS +field of tunnel packets is zeroed; with hidetos=no, it is copied from the +packet inside. (This is a modest security hole, which is why it is no +longer the default.) + +DiffServ does not interact well with tunneling in general. Ways of +improving this are being studied.</pre> + +<p>Copying the <a href="glossary.html#TOS">TOS</a> (type of service) +information from the encapsulated packet to the outer header reveals the TOS +information to an eavesdropper. This does not tell him much, but it might be +of use in <a href="glossary.html#traffic">traffic analysis</a>. Since we do +not have to give it to him, our default is not to.</p> + +<P>Even with the TOS hidden, you can still:</P> +<UL> +<LI>apply QOS rules to the tunneled (ESP) packets; for example, by +giving ESP packets a certain priority.</LI> +<LI>apply QOS rules to the packets as they enter or exit the tunnel +via an IPsec virtual interface (eg. <VAR>ipsec0</VAR>).</LI> +</UL> + +<p>See <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> for more on +the <var>hidetos=</var> parameter.</p> + + +<h3><a name="deadtunnel">Can I recognise dead tunnels and shut them +down?</a></h3> + +<p>There is no general mechanism to do this is in the IPsec protocols.</p> + +<p>From time to time, there is discussion on the IETF Working Group <a +href="mail.html#ietf">mailing list</a> of adding a "keep-alive" mechanism +(which some say should be called "make-dead"), but it is a fairly complex +problem and no consensus has been reached on whether or how it should be +done.</p> + +<p>The protocol does have optional <a href="#ignore">delete-SA</a> messages +which one side can send when it closes a connection in hopes this will cause +the other side to do the same. FreeS/WAN does not currently support these. In +any case, they would not solve the problem since:</p> +<ul> + <li>a gateway that crashes or hangs would not send the messages</li> + <li>the sender is not required to send them</li> + <li>they are not authenticated, so any receiver that trusts them leaves + itself open to a <a href="glossary.html#DOS">denial of service</a> + attack</li> + <li>the receiver is not required to do anything about them</li> + <li>the receiver cannot acknowledge them; the protocol provides no + mechanism for that</li> + <li>since they are not acknowledged, the sender cannot rely on them</li> +</ul> + +<p>However, connections do have limited lifetimes and you can control how +many attempts your gateway makes to rekey before giving up. For example, you +can set:</p> +<pre>conn default + keyingtries=3 + keylife=30m</pre> + +<p>With these settings old connections will be cleaned up. Within 30 minutes +of the other end dying, rekeying will be attempted. If it succeeds, the new +connection replaces the old one. If it fails, no new connection is created. +Either way, the old connection is taken down when its lifetime expires.</p> + +<p>Here is a mailing list message on the topic from FreeS/WAN tech support +person Claudia Schmeing:</p> +<pre>You ask how to determine whether a tunnel is redundant: + +> Can anybody explain the best way to determine this. Esp when a RW has +> disconnected? I thought 'ipsec auto --status' might be one way. + +If a tunnel goes down from one end, Linux FreeS/WAN on the +other end has no way of knowing this until it attempts to rekey. +Once it tries to rekey and fails, it will 'know' that the tunnel is +down. + +Because it doesn't have a way of knowing the state until this point, +it will also not be able to tell you the state via ipsec auto --status. + +> However, comparing output from a working tunnel with that of one that +> was closed +> did not show clearly show tunnel status. + +If your tunnel is down but not 'unrouted' (see man ipsec_auto), you +should not be able to ping the opposite side of the tunnel. You can +use this as an indicator of tunnel status. + +On a related note, you may be interested to know that as of 1.7, +redundant tunnels caused by RW disconnections are likely to be +less of a pain. From doc/CHANGES: + + There is a new configuration parameter, uniqueids, to control a new Pluto + option: when a new connection is negotiated with the same ID as an old + one, the old one is deleted immediately. This should help eliminate + dangling Road Warrior connections when the same Road Warrior reconnects. + It thus requires that IDs not be shared by hosts (a previously legal but + probably useless capability). NOTE WELL: the sample ipsec.conf now has + uniqueids=yes in its config-setup section. + + +Cheers, + +Claudia</pre> + +<h3><a name="demanddial">Can I build IPsec tunnels over a demand-dialed +link?</a></h3> + +<p>This is possible, but not easy. FreeS/WAN technical lead Henry Spencer +wrote:</p> +<pre>> 5. If the ISDN link goes down in between and is reestablished, the SAs +> are still up but the eroute are deleted and the IPsec interface shows +> garbage (with ifconfig) +> 6. Only restarting IPsec will bring the VPN back online. + +This one is awkward to solve. If the real interface that the IPsec +interface is mounted on goes down, it takes most of the IPsec machinery +down with it, and a restart is the only good way to recover. + +The only really clean fix, right now, is to split the machines in two: + +1. A minimal machine serves as the network router, and only it is aware +that the link goes up and down. + +2. The IPsec is done on a separate gateway machine, which thinks it has +a permanent network connection, via the router. + +This is clumsy but it does work. Trying to do both functions within a +single machine is tricky. There is a software package (diald) which will +give the illusion of a permanent connection for demand-dialed modem +connections; I don't know whether it's usable for ISDN, or whether it can +be made to cooperate properly with FreeS/WAN. + +Doing a restart each time the interface comes up *does* work, although it +is a bit painful. I did that with PPP when I was running on a modem link; +it wasn't hard to arrange the PPP scripts to bring IPsec up and down at +the right times. (I'd meant to investigate diald but never found time.) + +In principle you don't need to do a complete restart on reconnect, but you +do have to rebuild some things, and we have no nice clean way of doing +only the necessary parts.</pre> + +<p>In the same thread, one user commented:</p> +<pre>Subject: Re: linux-ipsec: IPsec and Dial Up Connections + Date: Wed, 22 Nov 2000 + From: Andy Bradford <andyb@calderasystems.com> + +On Wed, 22 Nov 2000 19:47:11 +0100, Philip Reetz wrote: + +> Are there any ideas what might be the cause of the problem and any way +> to work around it. +> Any help is highly appreciated. + +On my laptop, when using ppp there is a ip-up script in /etc/ppp that +will be executed each time that the ppp interface is brought up. +Likewise there is an ip-down script that is called when it is taken +down. You might consider custimzing those to stop and start FreeS/WAN +with each connection. I believe that ISDN uses the same files, though +I could be wrong---there should be something similar though.</pre> + +<h3><a name="GRE">Can I build GRE, L2TP or PPTP tunnels over IPsec?</a></h3> + +<p>Yes. Normally this is not necessary, but it is useful in a few special +cases. For example, if you must route non-IP packets such as IPX, you +will need to use a tunneling protocol that can route these packets. IPsec +can be layered around it for extra security. Another example: you +can provide failover protection for high availability (HA) environments by +combining IPsec with other tools. Ken Bantoft describes one such setup in +<A HREF="http://www.freeswan.ca/docs/HA">Using FreeS/WAN with Linux-HA, GRE, +OSPF and BGP for enterprise grade VPN solutions</A>.</P> + +<p>GRE over IPsec is covered as part of +<A HREF="http://www.freeswan.ca/docs/HA">that document</A>. +<a href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/07/msg00209.html"> +Here are links</a> to other GRE resources. + +Jacco de Leuw has created +<A HREF="http://www.jacco2.dds.nl/networking/">this page on L2TP over IPsec</A> +with instructions for FreeS/WAN and several other brands of IPsec software. +</P> + +<P>Please let us know of other useful links via the +<A HREF="mail.html">mailing lists</A>. + + +<h3><a name="NetBIOS">... use Network Neighborhood (Samba, NetBIOS) over IPsec?</a></h3> + +<p>Your local PC needs to know how to translate NetBIOS names to IP addresses. +It may do this either via a local LMHOSTS file, or using a local or remote +WINS server. The WINS server is preferable since it provides a centralized +source of the information to the entire network. To use a WINS server over +the <A HREF="glossary.html#VPN">VPN</A> +(or any IP-based network), you must enable "NetBIOS over TCP".</p> + +<p><A HREF="http://www.samba.org">Samba</A> can emulate a WINS server +on Linux.</p> + +<p> +See also several discussions in our +<A HREF="http://lists.freeswan.org/pipermail/users/2002-September/thread.html">September +2002 Users archives</A></p> + + +<h2><a name="setup.faq">Life's little mysteries</a></h2> + +<p>FreeS/WAN is a fairly complex product. (Neither the networks it runs on +nor the protocols it uses are simple, so it could hardly be otherwise.) It +therefore sometimes exhibits behaviour which can be somewhat confusing, or +has problems which are not easy to diagnose. This section tries to explain +those problems.</p> + +<p>Setup and configuration of FreeS/WAN are covered in other documentation +sections:</p> +<ul> + <li><a href="quickstart.html">basic setup and configuration</a></li> + <li><a href="adv_config.html">advanced configuration</a></li> + <li><a href="trouble.html">Troubleshooting</a></li> +</ul> + +<p>However, we also list some of the commonest problems here.</p> + +<h3><a name="cantping">I cannot ping ....</a></h3> + +<p>This question is dealt with in the advanced configuration section under +the heading <a href="adv_config.html#multitunnel">multiple tunnels</a>.</p> + +<p>The standard subnet-to-subnet tunnel protects traffic <strong>only between +the subnets</strong>. To test it, you must use pings that go from one subnet +to the other.</p> + +<p>For example, suppose you have:</p> +<pre> subnet a.b.c.0/24 + | + eth1 = a.b.c.1 + gate1 + eth0 = 192.0.2.8 + | + + ~ internet ~ + + | + eth0 = 192.0.2.11 + gate2 + eth1 = x.y.z.1 + | + subnet x.y.z.0/24</pre> + +<p>and the connection description:</p> +<pre>conn abc-xyz + left=192.0.2.8 + leftsubnet=a.b.c.0/24 + right=192.0.2.11 + rightsubnet=x.y.z.0/24</pre> + +<p>You can test this connection description only by sending a ping that will +actually go through the tunnel. Assuming you have machines at addresses +a.b.c.2 and x.y.z.2, pings you might consider trying are:</p> +<dl> + <dt>ping from x.y.z.2 to a.b.c.2 or vice versa</dt> + <dd>Succeeds if tunnel is working. This is the <strong>only valid test of + the tunnel</strong>.</dd> + <dt>ping from gate2 to a.b.c.2 or vice versa</dt> + <dd><strong>Does not use tunnel</strong>. gate2 is not on protected + subnet.</dd> + <dt>ping from gate1 to x.y.z.2 or vice versa</dt> + <dd><strong>Does not use tunnel</strong>. gate1 is not on protected + subnet.</dd> + <dt>ping from gate1 to gate2 or vice versa</dt> + <dd><strong>Does not use tunnel</strong>. Neither gate is on a protected + subnet.</dd> +</dl> + +<p>Only the first of these is a useful test of this tunnel. The others do not +use the tunnel. Depending on other details of your setup and routing, +they:</p> +<ul> + <li>either fail, telling you nothing about the tunnel</li> + <li>or succeed, telling you nothing about the tunnel since these packets + use some other route</li> +</ul> + +<p>In some cases, you may be able to get around this. For the example network +above, you could use:</p> +<pre> ping -I a.b.c.1 x.y.z.1</pre> + +<p>Both the adresses given are within protected subnets, so this should go +through the tunnel.</p> + +<p>If required, you can build additional tunnels so that all the machines +involved can talk to all the others. See <a +href="adv_config.html#multitunnel">multiple tunnels</a> in the advanced +configuration document for details.</p> + +<h3><a name="forever">It takes forever to ...</a></h3> + +<p>Users fairly often report various problems involving long delays, +sometimes on tunnel setup and sometimes on operations done through the +tunnel, occasionally on simple things like ping or more often on more complex +operations like doing NFS or Samba through the tunnel.</p> + +<p>Almost always, these turn out to involve failure of a DNS lookup. The +timeouts waiting for DNS are typically set long so that you won't time out +when a query involves multiple lookups or long paths. Genuine failures +therefore produce long delays before they are detected.</p> + +<p>A mailing list message from project technical lead Henry Spencer:</p> +<pre>> ... when i run /etc/rc.d/init.d/ipsec start, i get: +> ipsec_setup: Starting FreeS/WAN IPsec 1.5... +> and it just sits there, doesn't give back my bash prompt. + +Almost certainly, the problem is that you're using DNS names in your +ipsec.conf, but DNS lookups are not working for some reason. You will +get your prompt back... eventually. But the DNS timeouts are long. +Doing something about this is on our list, but it is not easy.</pre> + +<p>In the meanwhile, we recommend that connection descriptions in <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> use numeric IP addresses +rather than names which will require a DNS lookup.</p> + +<p>Names that do not require a lookup are fine. For example:</p> +<ul> + <li>a road warrior might use the identity + <var>rightid=@lancelot.example.org</var></li> + <li>the gateway might use <var>leftid=@camelot.example.org</var></li> +</ul> + +<p>These are fine. The @ sign prevents any DNS lookup. However, do not +attempt to give the gateway address as <var>left=camelot.example.org</var>. +That requires a lookup.</p> + +<p>A post from one user after solving a problem with long delays:</p> +<pre>Subject: Final Answer to Delay!!! + Date: Mon, 19 Feb 2001 + From: "Felippe Solutions" <felippe@solutionstecnologia.com.br> + +Sorry people, but seems like the Delay problem had nothing to do with +freeswan. + +The problem was DNS as some people sad from the beginning, but not the way +they thought it was happening. Samba, ssh, telnet and other apps try to +reverse lookup addresses when you use IP numbers (Stupid that ahh). + +I could ping very fast because I always ping with "-n" option, but I don't +know the option on the other apps to stop reverse addressing so I don't use +it.</pre> + +<p>This post is fairly typical. These problems are often tricky and +frustrating to diagnose, and most turn out to be DNS-related.</p> + +<p>One suggestion for diagnosis: test with both names and addresses if +possible. For example, try all of:</p> +<ul> + <li>ping <var>address</var></li> + <li>ping -n <var>address</var></li> + <li>ping <var>name</var></li> +</ul> + +<p>If these behave differently, the problem must be DNS-related since the +three commands do exactly the same thing except for DNS lookups.</p> + +<h3><a name="route">I send packets to the tunnel with route(8) but they +vanish</a></h3> + +<p>IPsec connections are designed to carry only packets travelling between +pre-defined connection endpoints. As project technical lead Henry Spencer put +it:</p> + +<blockquote> + IPsec tunnels are not just virtual wires; they are virtual wires with + built-in access controls. Negotiation of an IPsec tunnel includes + negotiation of access rights for it, which don't include packets to/from + other IP addresses. (The protocols themselves are quite inflexible about + this, so there are limits to what we can do about it.)</blockquote> + +<p>For fairly obvious security reasons, and to comply with the IPsec RFCs, <a +href="glossary.html#KLIPS">KLIPS</a> drops any packets it receives that are +not allowed on the tunnels currently defined. So if you send it packets with +<var>route(8)</var>, and suitable tunnels are not defined, the packets +vanish. Whether this is reported in the logs depends on the setting of +<var>klipsdebug</var> in your <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file.</p> + +<p>To rescue vanishing packets, you must ensure that suitable tunnels for +them exist, by editing the connection descriptions in <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>. For example, supposing +you have a simple setup:</p> +<pre> leftsubnet -- leftgateway === internet === roadwarrior</pre> + +<p>If you want to give the roadwarrior access to some resource that is +located behind the left gateway but is not in the currently defined left +subnet, then the usual procedure is to define an additional tunnel for those +packets by creating a new connection description.</p> + +<p>In some cases, it may be easier to alter an existing connection +description, enlarging the definition of <var>leftsubnet</var>. For example, +instead of two connection descriptions with 192.168.8.0/24 and 192.168.9.0/24 +as their <var>leftsubnet</var> parameters, you can use a single description +with 192.168.8.0/23.</p> + +<p>If you have multiple endpoints on each side, you need to ensure that there +is a route for each pair of endpoints. See this <a +href="adv_config.html#multitunnel">example</a>.</p> + +<h3><a name="down_route">When a tunnel goes down, packets vanish</a></h3> + +<p>This is a special case of the vanishing packet problem described in the +previous question. Whenever KLIPS sees packets for which it does not have a +tunnel, it drops them.</p> + +<p>When a tunnel goes away, either because negotiations with the other +gateway failed or because you gave an <var>ipsec auto --down</var> command, +the route to its other end is left pointing into KLIPS, and KLIPS will drop +packets it has no tunnel for.</p> + +<p>This is a documented design decision, not a bug. FreeS/WAN must not +automatically adjust things to send packets via another route. The other +route might be insecure.</p> + +<p>Of course, re-routing may be necessary in many cases. In those cases, you +have to do it manually or via scripts. We provide the <var>ipsec auto +--unroute</var> command for these cases.</p> + +<p>From <a href="manpage.d/ipsec_auto.8.html">ipsec_auto(8)</a>:</p> + +<blockquote> + Normally, pluto establishes a route to the destination specified for a + connection as part of the --up operation. However, the route and only + the route can be established with the --route operation. Until and unless + an actual connection is established, this discards any packets sent + there, which may be preferable to having them sent elsewhere based on a + more general route (e.g., a default route).</blockquote> + +<blockquote> + Normally, pluto's route to a destination remains in place when a --down + operation is used to take the connection down (or if connection setup, or + later automatic rekeying, fails). This permits establishing a new + connection (perhaps using a different specification; the route is altered + as necessary) without having a ``window'' in which packets might go + elsewhere based on a more general route. Such a route can be removed + using the --unroute operation (and is implicitly removed by +--delete).</blockquote> + +<p>See also this mailing list <a +href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00523.html">message</a>.</p> + +<h3><a name="firewall_ate">The firewall ate my packets!</a></h3> + +<p>If firewalls filter out:</p> +<ul> + <li>either the UDP port 500 packets used in IKE negotiations</li> + <li>or the ESP and AH (protocols 50 and 51) packets used to implement the + IPsec tunnel</li> +</ul> + +<p>then IPsec cannot work. The first thing to check if packets seem to be +vanishing is the firewall rules on the two gateway machines and any other +machines along the path that you have access to.</p> + +<p>For details, see our document on <a href="firewall.html">firewalls</a>.</p> + +<p>Some advice from technical lead Henry Spencer on diagnosing such +problems:</p> +<pre>> > Packets vanishing between the hardware interface and the ipsecN interface +> > is usually the result of firewalls not being configured to let them in... +> +> Thanks for the suggestion. If only it were that simple! My ipchains startup +> script does take care of that, but just in case I manually inserted rules +> accepting everything from london on dublin. No difference. + +The other thing to check is whether the "RX packets dropped" count on the +ipsecN interface (run "ifconfig ipsecN", for N=1 or whatever, to see the +counts) is rising. If so, then there's some sort of configuration mismatch +between the two ends, and IPsec itself is rejecting them. If none of the +ipsecN counts is rising, then the packets are never reaching the IPsec +machinery, and the problem is almost certainly in firewalls etc.</pre> + +<h3><a name="dropconn">Dropped connections</a></h3> + +<p>Networks being what they are, IPsec connections can be broken for any +number of reasons, ranging from hardware failures to various software +problems such as the path MTU problems discussed <a +href="#pmtu.broken">elsewhere in the FAQ</a>. Fortunately, various diagnostic +tools exist that help you sort out many of the possible problems.</p> + +<p>There is one situation, however, where FreeS/WAN (using default settings) +may destroy a connection for no readily apparent reason. This occurs when +things are <strong>misconfigured</strong> so that <strong>two +tunnels</strong> from the same gateway expect <strong>the same subnet on the +far end</strong>.</p> + +<p>In this situation, the first tunnel comes up fine and works until the +second is established. At that point, because of the way we track connections +internally, the first tunnel ceases to exist as far as this gateway is +concerned. Of course the far end does not know that, and a storm of error +messages appears on both systems as it tries to use the tunnel.</p> + +<p>If the far end gives up, goes back to square one and negotiates a new +tunnel, then that wipes out the second tunnel and ...</p> + +<p>The solution is simple. <strong>Do not build multiple conn descriptions +with the same remote subnet</strong>.</p> + +<p>This is actually intended to be a feature, rather than a bug. Consider the +situation where a single remote system goes down, then comes back up and +reconnects to the gateway. It is useful to have the gateway tear down the old +tunnel and recover resources when the reconnection is made. It recognises +that situation by checking the remote subnet for each tunnel it builds and +discarding duplicates. This works fine as long as you don't configure +multiple tunnels with the same remote subnet.</p> + +<p>If this behaviour is inconvenient for you, you can disable it by setting +<var>uniqueids=no</var> in <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.</p> + + +<h3><a name="defaultroutegone">Disappearing %defaultroute</a></h3> + +<p>When an underlying connection (eg. ppp) goes down, FreeS/WAN will not +recover properly without a little help. Here are the symptoms that FreeS/WAN +user Michael Carmody noticed: +<pre> +> After about 24 hours the freeswan connection takes over the default route. +> +> i.e instead of deafult gateway pointing to the router via eth0, it becomes a +> pointer to the router via ipsec0. + +> All internet access is then lost as all replies (and not just the link I +> wanted) are routed out ipsec0 and the router doesn't respond to the ipsec +> traffic. +</pre> + +<p>If you're using a +FreeS/WAN 2.x/KLIPS system, simply re-attach the IPsec virtual +interface with <em>ipsec tnconfig</em> command such as:</p> +<pre> ipsec tnconfig --attach --virtual ipsec0 --physical ppp0</pre> +<p>In your command, name the physical and virtual interfaces as they +appear paired on your system during regular uptime. For a system with several +physical/virtual interface pairs on flaky links, you'll need more than +one such command. +If you're using FreeS/WAN 1.x, you must restart FreeS/WAN, which is more time +consuming.</p> + +<p> +<A href="http://lists.freeswan.org/pipermail/design/2002-July/003070.html">Here</A> +is a script which can help to automate the process of FreeS/WAN restart at +need. +It could easily be adapted to use tnconfig instead.</p> + +<h3><a name="tcpdump.faq">TCPdump on the gateway shows strange things</a></h3> + +As another user pointed out, keeping the connect +<p>Attempting to look at IPsec packets by running monitoring tools on the +IPsec gateway machine can produce silly results. That machine is mangling the +packets for IPsec, and possibly for firewall or NAT purposes as well. If the +internals of the machine's IP stack are not what the monitoring tool expects, +then the tool can misinterpret them and produce nonsense output.</p> + +<p>See our <a href="testing.html#tcpdump.test">testing</a> document for more +detail.</p> + +<h3><a name="no_trace">Traceroute does not show anything between the +gateways</a></h3> + +<p>As far as traceroute can see, the two gateways are one hop apart; the data +packet goes directly from one to the other through the tunnel. Of course the +outer packets that implement the tunnel pass through whatever lies between +the gateways, but those packets are built and dismantled by the gateways. +Traceroute does not see them and cannot report anything about their path.</p> + +<p>Here is a mailing list message with more detail.</p> +<pre>Date: Mon, 14 May 2001 +To: linux-ipsec@freeswan.org +From: "John S. Denker" <jsd@research.att.com< +Subject: Re: traceroute: one virtual hop + +At 02:20 PM 5/14/01 -0400, Claudia Schmeing wrote: +> +>> > A bonus question: traceroute in subnet to subnet enviroment looks like: +>> > +>> > traceroute to andris.dmz (172.20.24.10), 30 hops max, 38 byte packets +>> > 1 drama (172.20.1.1) 0.716 ms 0.942 ms 0.434 ms +>> > 2 * * * +>> > 3 andris.dmz (172.20.24.10) 73.576 ms 78.858 ms 79.434 ms +>> > +>> > Why aren't there the other hosts which take part in the delivery during +> * * * ? +> +>If there is an ipsec tunnel between GateA and Gate B, this tunnel forms a +>'virtual wire'. When it is tunneled, the original packet becomes an inner +>packet, and new ESP and/or AH headers are added to create an outer packet +>around it. You can see an example of how this is done for AH at +>doc/ipsec.html#AH . For ESP it is similar. +> +>Think about the packet's path from the inner packet's perspective. +>It leaves the subnet, goes into the tunnel, and re-emerges in the second +>subnet. This perspective is also the only one available to the +>'traceroute' command when the IPSec tunnel is up. + +Claudia got this exactly right. Let me just expand on a couple of points: + +*) GateB is exactly one (virtual) hop away from GateA. This is how it +would be if there were a physically private wire from A to B. The +virtually private connection should work the same, and it does. + +*) While the information is in transit from GateA to GateB, the hop count +of the outer header (the "envelope") is being decremented. The hop count +of the inner header (the "contents" of the envelope) is not decremented and +should not be decremented. The hop count of the outer header is not +derived from and should not be derived from the hop count of the inner header. + +Indeed, even if the packets did time out in transit along the tunnel, there +would be no way for traceroute to find out what happened. Just as +information cannot leak _out_ of the tunnel to the outside, information +cannot leak _into_ the tunnel from outside, and this includes ICMP messages +from routers along the path. + +There are some cases where one might wish for information about what is +happening at the IP layer (below the tunnel layer) -- but the protocol +makes no provision for this. This raises all sorts of conceptual issues. +AFAIK nobody has ever cared enough to really figure out what _should_ +happen, let alone implement it and standardize it. + +*) I consider the "* * *" to be a slight bug. One might wish for it to be +replaced by "GateB GateB GateB". It has to do with treating host-to-subnet +traffic different from subnet-to-subnet traffic (and other gory details). +I fervently hope KLIPS2 will make this problem go away. + +*) If you want to ask questions about the link from GateA to GateB at the +IP level (below the tunnel level), you have to ssh to GateA and launch a +traceroute from there.</pre> + +<h2><a name="man4debug">Testing in stages</a></h2> + +<p>It is often useful in debugging to test things one at a time:</p> +<ul> + <li>disable IPsec entirely, for example by turning it off with + chkconfig(8), and make sure routing works</li> + <li>Once that works, try a manually keyed connection. This does not require + key negotiation between Pluto and the key daemon on the other end.</li> + <li>Once that works, try automatically keyed connections</li> + <li>Once IPsec works, add packet compression</li> + <li>Once everything seems to work, try stress tests with large transfers, + many connections, frequent re-keying, ...</li> +</ul> + +<p>FreeS/WAN releases are tested for all of these, so you can be reasonably +certain they <em>can</em> do them all. Of course, that does not mean they +<em>will</em> on the first try, especially if you have some unusual +configuration.</p> + +<p>The rest of this section gives information on diagnosing the problem when +each of the above steps fails.</p> + +<h3><a name="nomanual">Manually keyed connections don't work</a></h3> + +<p>Suspect one of:</p> +<ul> + <li>mis-configuration of IPsec system in the /etc/ipsec.conf file<br> + common errors are incorrect interface or next hop information</li> + <li>mis-configuration of manual connection in the /etc/ipsec.conf file</li> + <li>routing problems causing IPsec packets to be lost</li> + <li>bugs in KLIPS</li> + <li>mismatch between the transforms we support and those another IPsec + implementation offers.</li> +</ul> + +<h3><a name="spi_error">One manual connection works, but second one +fails</a></h3> + +<p>This is a fairly common problem when attempting to configure multiple +manually keyed connections from a single gateway.</p> + +<p>Each connection must be identified by a unique <a +href="glossary.html#SPI">SPI</a> value. For automatic connections, these +values are assigned automatically. For manual connections, you must set them +with <var>spi=</var> statements in <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.</p> + +<p>Each manual connection must have a unique SPI value in the range 0x100 to +0x999. Two or more with the same value will fail. For details, see our doc +section <a href="adv_config.html#prodman">Using manual keying in +production</a> and the man page <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.</p> + +<h3><a name="man_no_auto">Manual connections work, but automatic keying +doesn't</a></h3> + +<p>The most common reason for this behaviour is a firewall dropping the UDP +port 500 packets used in key negotiation.</p> + +<p>Other possibilities:</p> +<ul> + <li>mis-configuration of auto connection in the /etc/ipsec.conf file. + <p>One common configuration error is forgetting that you need + <var>auto=add</var> to load the connection description on the receiving + end so it recognises the connection when the other end asks for it.</p> + </li> + <li>error in shared secret in /etc/ipsec.secrets</li> + <li>one gateway lacks a route to the other so Pluto's UDP packets are + lost</li> + <li>bugs in Pluto</li> + <li>incompatibilities between Pluto's <a href="glossary.html#IKE">IKE</a> + implementation and the IKE at the other end of the tunnel. + <p>Some possibile problems are discussed in out <a + href="interop.html#interop.problem">interoperation</a> document.</p> + </li> +</ul> + +<h3><a name="nocomp">IPsec works, but connections using compression +fail</a></h3> + +<p>When we first added compression, we saw some problems:</p> +<ul> + <li>compatibility issues with other implementations. We followed the RFCs + and omitted some extra material that many compression libraries add by + default. Some other implementations left the extras in</li> + <li>bugs in assembler compression routines on non-Intel CPUs. The + workaround is to use C code instead of possibly problematic + assembler.</li> +</ul> + +<p>We have not seen either problem in some time (at least six months as I +write in March 2002), but if you have some unusual configuration then you may +see them.</p> + +<h3><a name="pmtu.broken">Small packets work, but large transfers +fail</a></h3> + +<p>If tests with ping(1) and a small packet size succeed, but tests or +transfers with larger packet sizes fail, suspect problems with packet +fragmentation and perhaps <a href="glossary.html#pathMTU">path MTU +discovery</a>.</p> + +<p>Our <a href="trouble.html#bigpacket">troubleshooting document</a> covers +these problems. Information on the underlying mechanism is in our <a +href="background.html#MTU.trouble">background</a> document.</p> + +<h3><a name="subsub">Subnet-to-subnet works, but tests from the gateways +don't</a></h3> + +<p>This is described under <a href="#cantping">I cannot ping...</a> above.</p> + +<h2><a name="compile.faq">Compilation problems</a></h2> + +<h3><a name="gmp.h_missing">gmp.h: No such file or directory</a></h3> + +<p>Pluto needs the GMP (<strong>G</strong>NU</p> + +<p><strong>M</strong>ulti-<strong>P</strong>recision) library for the large +integer calculations it uses in <a href="glossary.html#public">public key</a> +cryptography. This error message indicates a failure to find the library. You +must install it before Pluto will compile.</p> + +<p>The GMP library is included in most Linux distributions. Typically, there +are two RPMs, libgmp and libgmp-devel, You need to <em>install both</em>, +either from your distribution CDs or from your vendor's web site.</p> + +<p>On Debian, a mailing list message reports that the command to give is +<var>apt-get install gmp2</var>.</p> + +<p>For more information and the latest version, see the <a +href="http://www.swox.com/gmp/">GMP home page</a>.</p> + +<h3><a name="noVM">... virtual memory exhausted</a></h3> + +<p>We have had several reports of this message appearing, all on SPARC Linux. +Here is a mailing message on a solution:</p> +<pre>> ipsec_sha1.c: In function `SHA1Transform': +> ipsec_sha1.c:95: virtual memory exhausted + +I'm seeing exactly the same problem on an Ultra with 256MB ram and 500 +MB swap. Except I am compiling version 1.5 and its Red Hat 6.2. + +I can get around this by using -O instead of -O2 for the optimization +level. So it is probably a bug in the optimizer on the sparc complier. +I'll try and chase this down on the sparc lists.</pre> + +<h2><a name="error">Interpreting error messages</a></h2> + +<h3><a name="route-client">route-client (or host) exited with status +7</a></h3> + +<p>Here is a discussion of this error from FreeS/WAN "listress" (mailing list +tech support person) Claudia Schmeing. The "FAQ on the network unreachable +error" which she refers to is the next question below.</p> +<pre>> I reached the point where the two boxes (both on dial-up connections, but +> treated as static IPs by getting the IP and editing ipsec.conf after the +> connection is established) to the point where they exchange some info, but I +> get an error like "route-client command exited with status 7 \n internal +> error". +> Where can I find a description of this error? + +In general, if the FAQ doesn't cover it, you can search the mailing list +archives - I like to use +http://www.sandelman.ottawa.on.ca/linux-ipsec/ +but you can see doc/mail.html for different archive formats. + + +Your error comes from the _updown script, which performs some +routing and firewall functions to help Linux FreeS/WAN. More info +is available at doc/firewall.html and man ipsec.conf. Its routing +is integral to the health of Linux FreeS/WAN; it also provides facility +to insert custom firewall rules to be executed when you create or destroy +a connection. + +Yours is, of course, a routing error. You can be fairly sure the routing +machinery is saying "network is unreachable". There's a FAQ on the +"network is unreachable" error, but more information is available now; read on. + +If your _updown script is recent (for example if it shipped with +Linux FreeS/WAN 1.91), you will see another debugging line in your logs +that looks something like this: + +> output: /usr/local/lib/ipsec/_updown: `route add -net 128.174.253.83 +> netmask 255.255.255.255 dev ipsec0 gw 66.92.93.161' failed + +This is, of course, the system route command that exited with status 7, +(ie. failed). Man route for details. Seeing the command typed out yields +more information. If your _updown script is older, you may wish to update +it to show the command explicitly. + +Three parameters fed to the route command: net, netmask and gw [gateway] +are derived from things you've put in ipsec.conf. + +Net and netmask are derived from the peer's IP and mask. In more detail: + +You may see a routing error when routing to a client (ie. subnet), or +to a host (IPSec gateway or freestanding host; a box that does IPSec for +itself). In _updown, the "route-client" section is responsible to set up +the route for IPSec'd (usually, read 'tunneled') packets headed to a +peer subnet. Similarly, route-host routes IPSec'd packets to a peer host +or IPSec gateway. + +When routing to a 'client', net and netmask are ipsec.conf's left- or +rightsubnet (whichever is not local). Similarly, when routing to a +'host' the net is left or right. Host netmask is always /32, indicating a +single machine. + +Gw is nexthop's value. Again, the value in question is left- or rightnexthop, +whichever is local. Where left/right or left-/rightnexthop has the special +value %defaultroute (described in man ipsec.conf), gw will automagically get +the value of the next hop on the default route. + +Q: "What's a nexthop and why do I need one?" + +A: 'nexthop' is a routing kluge; its value is the next hop away + from the machine that's doing IPSec, and toward your IPSec peer. + You need it to get the processed packets out of the local system and + onto the wire. While we often route other packets through the machine + that's now doing IPSec, and are done with it, this does not suffice here. + After packets are processed with IPSec, this machine needs to know where + they go next. Of course using the 'IPSec gateway' as their routing gateway + would cause an infinite loop! [To visualize this, see the packet flow + diagram at doc/firewall.html.] To avoid this, we route packets through + the next hop down their projected path. + +Now that you know the background, consider: +1. Did you test routing between the gateways in the absence of Linux + FreeS/WAN, as recommended? You need to ensure the two machines that + will be running Linux FreeS/WAN can route to one another before trying to + make a secure connection. +2. Is there anything obviously wrong with the sense of your route command? + +Normally, this problem is caused by an incorrect local nexthop parameter. +Check out the use of %defaultroute, described in man ipsec.conf. This is +a simple way to set nexthop for most people. To figure nexthop out by hand, +traceroute in-the-clear to your IPSec peer. Nexthop is the traceroute's +first hop after your IPSec gateway.</pre> + +<h3><a name="unreachable">SIOCADDRT:Network is unreachable</a></h3> + +<p>This message is not from FreeS/WAN, but from the Linux IP stack itself. +That stack is seeing packets it has no route for, either because your routing +was broken before FreeS/WAN started or because FreeS/WAN's changes broke +it.</p> + +<p>Here is a message from Claudia suggesting ways to diagnose and fix such +problems:</p> +<pre>You write, +> I have correctly installed freeswan-1.8 on RH7.0 kernel 2.2.17, but when +> I setup a VPN connection with the other machine(RH5.2 Kernel 2.0.36 +> freeswan-1.0, it works well.) it told me that +> "SIOCADDRT:Network is unreachable"! But the network connection is no +> problem. + +Often this error is the result of a misconfiguration. + +Be sure that you can route successfully in the absence of Linux +FreeS/WAN. (You say this is no problem, so proceed to the next step.) + +Use a custom copy of the default updownscript. Do not change the route +commands, but add a diagnostic message revealing the exact text of the +route command. Is there a problem with the sense of the route command +that you can see? If so, then re-examine those ipsec.conf settings +that are being sent to the route command. + +You may wish to use the ipsec auto --route and --unroute commands to +troubleshoot the problem. See man ipsec_auto for details.</pre> + +<p>Since the above message was written, we have modified the updown script to +provide a better diagnostic for this problem. Check +<var>/var/log/messages</var>.</p> + +<p>See also the FAQ question <a href="#route-client">route-client (or host) +exited with status 7</a>.</p> + +<h3><a name="modprobe">ipsec_setup: modprobe: Can't locate module +ipsec</a></h3> + +<h3><a name="noKLIPS">ipsec_setup: Fatal error, kernel appears to lack +KLIPS</a></h3> + +<p>These messages indicate an installation failure. The kernel you are +running does not contain the <a href="glossary.html#KLIPS">KLIPS (kernel +IPsec)</a> code.</p> + +<p>Note that the "modprobe: Can't locate module ipsec" message appears even +if you are not using modules. If there is no KLIPS in your kernel, FreeS/WAN +tries to load it as a module. If that fails, you get this message.</p> + +<p>Commands you can quickly try are:</p> +<dl> + <dt><var>uname -a</var></dt> + <dd>to get details, including compilation date and time, of the currently + running kernel</dd> + <dt><var>ls /</var></dt> + <dt><var>ls /boot</var></dt> + <dd>to ensure a new kernel is where it should be. If kernel compilation + puts it in <var>/</var> but <var>lilo</var> wants it in + <var>/boot</var>, then you should uncomment the + <var>INSTALL_PATH=/boot</var> line in the kernel + <var>Makefile</var>.</dd> + <dt><var>more /etc/lilo.conf</var></dt> + <dd>to see that <var>lilo</var> has correct information</dd> + <dt><var>lilo</var></dt> + <dd>to ensure that information in <var>/etc/lilo.conf</var> has been + transferred to the boot sector</dd> +</dl> + +<p>If those don't find the problem, you have to go back and check through the +<a href="install.html">install</a> procedure to see what was missed.</p> + +<p>Here is one of Claudia's messages on the topic:</p> +<pre>> I tried to install freeswan 1.8 on my mandrake 7.2 test box. ... + +> It does show version and some output for whack. + +Yes, because the Pluto (daemon) part of ipsec is installed correctly, but +as we see below the kernel portion is not. + +> However, I get the following from /var/log/messages: +> +> Mar 11 22:11:55 pavillion ipsec_setup: Starting FreeS/WAN IPsec 1.8... +> Mar 11 22:12:02 pavillion ipsec_setup: modprobe: Can't locate module ipsec +> Mar 11 22:12:02 pavillion ipsec_setup: Fatal error, kernel appears to lack +> KLIPS. + +This is your problem. You have not successfully installed a kernel with +IPSec machinery in it. + +Did you build Linux FreeS/WAN as a module? If so, you need to ensure that +your new module has been installed in the directory where your kernel +loader normally finds your modules. If not, you need to ensure +that the new IPSec-enabled kernel is being loaded correctly. + +See also doc/install.html, and INSTALL in the distro.</pre> + +<h3><a name="noDNS">ipsec_setup: ... failure to fetch key for ... from +DNS</a></h3> + +<p>Quoting Henry:</p> +<pre>Note that by default, FreeS/WAN is now set up to + (a) authenticate with RSA keys, and + (b) fetch the public key of the far end from DNS. +Explicit attention to ipsec.conf will be needed if you want +to do something different.</pre> + +<p>and Claudia, responding to the same user:</p> +<pre>You write, + +> My current setup in ipsec.conf is leftrsasigkey=%dns I have +> commented this and authby=rsasig out. I am able to get ipsec running, +> but what I find is that the documentation only specifies for %dns are +> there any other values that can be placed in this variable other than +> %dns and the key? I am also assuming that this is where I would place +> my public key for the left and right side as well is this correct? + +Valid values for authby= are rsasig and secret, which entail authentication +by RSA signature or by shared secret, respectively. Because you have +commented authby=rsasig out, you are using the default value of authby=secret. + +When using RSA signatures, there are two ways to get the public key for the +IPSec peer: either copy it directly into *rsasigkey= in ipsec.conf, or +fetch it from dns. The magic value %dns for *rsasigkey parameters says to +try to fetch the peer's key from dns. + +For any parameters, you may find their significance and special values in +man ipsec.conf. If you are setting up keys or secrets, be sure also to +reference man ipsec.secrets.</pre> + +<h3><a name="dup_address">ipsec_setup: ... interfaces ... and ... share +address ...</a></h3> + +<p>This is a fatal error. FreeS/WAN cannot cope with two or more interfaces +using the same IP address. You must re-configure to avoid this.</p> + +<p>A mailing list message on the topic from Pluto developer Hugh +Redelmeier:</p> +<pre>| I'm trying to get freeswan working between two machine where one has a ppp +| interface. +| I've already suceeded with two machines with ethernet ports but the ppp +| interface is causing me problems. +| basically when I run ipsec start i get +| ipsec_setup: Starting FreeS/WAN IPsec 1.7... +| ipsec_setup: 003 IP interfaces ppp1 and ppp0 share address 192.168.0.10! +| ipsec_setup: 003 IP interfaces ppp1 and ppp2 share address 192.168.0.10! +| ipsec_setup: 003 IP interfaces ppp0 and ppp2 share address 192.168.0.10! +| ipsec_setup: 003 no public interfaces found +| +| followed by lots of cannot work out interface for connection messages +| +| now I can specify the interface in ipsec.conf to be ppp0 , but this does +| not affect the above behaviour. A quick look in server.c indicates that the +| interfaces value is not used but some sort of raw detect happens. +| +| I guess I could prevent the formation of the extra ppp interfaces or +| allocate them different ip but I'd rather not. if at all possible. Any +| suggestions please. + +Pluto won't touch an interface that shares an IP address with another. +This will eventually change, but it probably won't happen soon. + +For now, you will have to give the ppp1 and ppp2 different addresses.</pre> + +<h3><a name="kflags">ipsec_setup: Cannot adjust kernel flags</a></h3> + +<p>A mailing list message form technical lead Henry Spencer:</p> +<pre>> When FreeS/WAN IPsec 1.7 is starting on my 2.0.38 Linux kernel the following +> error message is generated: +> ipsec_setup: Cannot adjust kernel flags, no /proc/sys/net/ipsec directory! +> What is supposed to create this directory and how can I fix this problem? + +I think that directory is a 2.2ism, although I'm not certain (I don't have +a 2.0.xx system handy any more for testing). Without it, some of the +ipsec.conf config-setup flags won't work, but otherwise things should +function. </pre> + +<p>You also need to enable the <var>/proc</var> filesystem in your kernel +configuration for these operations to work.</p> + +<h3><a name="message_num">Message numbers (MI3, QR1, et cetera) in Pluto +messages</a></h3> + +<p>Pluto messages often indicate where Pluto is in the IKE protocols. The +letters indicate <strong>M</strong>ain mode or <strong>Q</strong>uick mode +and <strong>I</strong>nitiator or <strong>R</strong>esponder. The numerals +are message sequence numbers. For more detail, see our <a +href="ipsec.html#sequence">IPsec section</a>.</p> + +<h3><a name="conn_name">Connection names in Pluto error messages</a></h3> + +<p>From Pluto programmer Hugh Redelmeier:</p> +<pre>| Jan 17 16:21:10 remus Pluto[13631]: "jumble" #1: responding to Main Mode from Road Warrior 130.205.82.46 +| Jan 17 16:21:11 remus Pluto[13631]: "jumble" #1: no suitable connection for peer @banshee.wittsend.com +| +| The connection "jumble" has nothing to do with the incoming +| connection requests, which were meant for the connection "banshee". + +You are right. The message tells you which Connection Pluto is +currently using, which need not be the right one. It need not be the +right one now for the negotiation to eventually succeed! This is +described in ipsec_pluto(8) in the section "Road Warrior Support". + +There are two times when Pluto will consider switching Connections for +a state object. Both are in response to receiving ID payloads (one in +Phase 1 / Main Mode and one in Phase 2 / Quick Mode). The second is +not unique to Road Warriors. In fact, neither is the first any more +(two connections for the same pair of hosts could differ in Phase 1 ID +payload; probably nobody else has tried this).</pre> + +<h3><a name="cantorient">Pluto: ... can't orient connection</a></h3> + +<p>Older versions of FreeS/WAN used this message. The same error now gives +the "we have no ipsecN ..." error described just below.</p> + +<h3><a name="no.interface">... we have no ipsecN interface for either end of +this connection</a></h3> + +<p>Your tunnel has no IP address which matches the IP +address of any of the available IPsec interfaces. Either you've +misconfigured the connection, or you need to define an appropriate +IPsec interface connection. <VAR>interfaces=%defaultroute</VAR> works +in many cases.</p> + +<p>A longer story: Pluto needs to know whether it is running on +the machine which the +connection description calls <var>left</var> or on <var>right</var>. It +figures that out by:</p> +<ul> + <li>looking at the interfaces given in <var>interfaces=</var> lines in the + <var>config setup</var> section</li> + <li>discovering the IP addresses for those interfaces</li> + <li>searching for a match between those addresses and the ones given in + <var>left=</var> or <var>right=</var> lines.</li> +</ul> + +<p>Normally a match is found. Then Pluto knows where it is and can set up +other things (for example, if it is <var>left</var>) using parameters such as +<var>leftsubnet</var> and <var>leftnexthop</var>, and sending its outgoing +packets to <var>right</var>.</p> + +<p>If no match is found, it emits the above error message.</p> + +<h3><a name="noconn">Pluto: ... no connection is known</a></h3> + +<p>This error message occurs when a remote system attempts to negotiate a +connection and Pluto does not have a connection description that matches what +the remote system has requested. The most common cause is a configuration +error on one end or the other.</p> + +<p>Parameters involved in this match are <var>left</var>, <var>right</var>, +<var>leftsubnet</var> and <var>rightsubnet</var>.</p> + +<p><strong>The match must be exact</strong>. For example, if your left subnet +is a.b.c.0/24 then neither a single machine in that net nor a smaller subnet +such as a.b.c.64/26 will be considered a match.</p> + +<p>The message can also occur when an appropriate description exists but +Pluto has not loaded it. Use an <var>auto=add</var> statement in the +connection description, or an <var>ipsec auto --add <conn_name></var> +command, to correct this.</p> + +<p>An explanation from the Pluto developer:</p> +<pre>| Jul 12 15:00:22 sohar58 Pluto[574]: "corp_road" #2: cannot respond to IPsec +| SA request because no connection is known for +| 216.112.83.112/32===216.112.83.112...216.67.25.118 + +This is the first message from the Pluto log showing a problem. It +means that PGPnet is trying to negotiate a set of SAs with this +topology: + +216.112.83.112/32===216.112.83.112...216.67.25.118 +^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^ ^^^^^^^^^^^^^ +client on our side our host PGPnet host, no client + +None of the conns you showed look like this. + +Use + ipsec auto --status +to see a snapshot of what connections are in pluto, what +negotiations are going on, and what SAs are established. + +The leftsubnet= (client) in your conn is 216.112.83.64/26. It must +exactly match what pluto is looking for, and it does not.</pre> + +<h3><a name="nosuit">Pluto: ... no suitable connection ...</a></h3> + +<p>This is similar to the <a href="#noconn">no connection known</a> error, +but occurs at a different point in Pluto processing.</p> + +<p>Here is one of Claudia's messages explaining the problem:</p> +<pre>You write, + +> What could be the reason of the following error? +> "no suitable connection for peer '@xforce'" + +When a connection is initiated by the peer, Pluto must choose which entry in +the conf file best matches the incoming connection. A preliminary choice is +made on the basis of source and destination IPs, since that information is +available at that time. + +A payload containing an ID arrives later in the negotiation. Based on this +id and the *id= parameters, Pluto refines its conn selection. ... + +The message "no suitable connection" indicates that in this refining step, +Pluto does not find a connection that matches that ID. + +Please see "Selecting a connection when responding" in man ipsec_pluto for +more details.</pre> + +<p>See also <a href="#conn_name">Connection names in Pluto error +messages</a>.</p> + +<h3><a name="noconn.auth">Pluto: ... no connection has been +authorized</a></h3> + +<p>Here is one of Claudia's messages discussing this problem:</p> +<pre>You write, + +> May 22 10:46:31 debian Pluto[25834]: packet from x.y.z.p:10014: +> initial Main Mode message from x.y.z.p:10014 + but no connection has been authorized + +This error occurs early in the connection negotiation process, +at the first step of IKE negotiation (Main Mode), which is itself the +first of two negotiation phases involved in creating an IPSec connection. + +Here, Linux FreeS/WAN receives a packet from a potential peer, which +requests that they begin discussing a connection. + +The "no connection has been authorized" means that there is no connection +description in Linux FreeS/WAN's internal database that can be used to +link your ipsec interface with that peer. + +"But of course I configured that connection!" + +It may be that the appropriate connection description exists in ipsec.conf +but has not been added to the database with ipsec auto --add myconn or the +auto=add method. Or, the connection description may be misconfigured. + +The only parameters that are relevant in this decision are left= and right= . +Local and remote ports are also taken into account -- we see that the port +is printed in the message above -- but there is no way to control these +in ipsec.conf. + + +Failure at "no connection has been authorized" is similar to the +"no connection is known for..." error in the FAQ, and the "no suitable +connection" error described in the snapshot's FAQ. In all three cases, +Linux FreeS/WAN is trying to match parameters received in the +negotiation with the connection description in the local config file. + +As it receives more information, its matches take more parameters into +account, and become more precise: first the pair of potential peers, +then the peer IDs, then the endpoints (including any subnets). + +The "no suitable connection for peer *" occurs toward the end of IKE +(Main Mode) negotiation, when the IDs are matched. + +"no connection is known for a/b===c...d" is seen at the beginning of IPSec +(Quick Mode, phase 2) negotiation, when the connections are matched using +left, right, and any information about the subnets.</pre> + +<h3><a name="noDESsupport">Pluto: ... OAKLEY_DES_CBC is not +supported.</a></h3> + +<p>This message occurs when the other system attempts to negotiate a +connection using <a href="glossary.html#DES">single DES</a>, which we do not +support because it is <a href="politics.html#desnotsecure">insecure</a>.</p> + +<p>Our interoperation document has suggestions for <a +href="interop.html#noDES">how to deal with</a> systems that attempt to use +single DES.</p> + +<h3><a name="notransform">Pluto: ... no acceptable transform</a></h3> + +<p>This message means that the other gateway has made a proposal for +connection parameters, but nothing they proposed is acceptable to Pluto. +Possible causes include:</p> +<ul> + <li>misconfiguration on either end</li> + <li>policy incompatibilities, for example we require encrypted connections + but they are trying to create one with just authentication</li> + <li>interoperation problems, for example they offer only single DES and + FreeS/WAN does not support that. See <a + href="interop.html#interop.problem">discussion</a> in our interoperation + document.</li> +</ul> + +<p>A more detailed explanation, from Pluto programmer Hugh Redelmeier:</p> +<pre>Background: + +When one IKE system (for example, Pluto) is negotiating with another +to create an SA, the Initiator proposes a bunch of choices and the +Responder replies with one that it has selected. + +The structure of the choices is fairly complicated. An SA payload +contains a list of lists of "Proposals". The outer list is a set of +choices: the selection must be from one element of this list. + +Each of these elements is a list of Proposals. A selection must be +made from each of the elements of the inner list. In other words, +*all* of them apply (that is how, for example, both AH and ESP can +apply at once). + +Within each of these Proposals is a list of Transforms. For each +Proposal selected, one Transform must be selected (in other words, +each Proposal provides a choice of Transforms). + +Each Transform is made up of a list of Attributes describing, well, +attributes. Such as lifetime of the SA. Such as algorithm to be +used. All the Attributes apply to a Transform. + +You will have noticed a pattern here: layers alternate between being +disjunctions ("or") and conjunctions ("and"). + +For Phase 1 / Main Mode (negotiating an ISAKMP SA), this structure is +cut back. There must be exactly one Proposal. So this degenerates to +a list of Transforms, one of which must be chosen. + +In your case, no proposal was considered acceptable to Pluto (the +Responder). So negotiation ceased. Pluto logs the reason it rejects +each Transform. So look back in the log to see what is going wrong.</pre> + +<h3><a name="rsasigkey">rsasigkey dumps core</a></h3> +A comment on this error from Henry: +<pre>On Fri, 29 Jun 2001, Rodrigo Gruppelli wrote: +> ...Well, it seem that there's +> another problem with it. When I try to generate a pair of RSA keys, +> rsasigkey cores dump... + +*That* is a neon sign flashing "GMP LIBRARY IS BROKEN". Rsasigkey calls +GMP a lot, and our own library a little bit, and that's very nearly all it +does. Barring bugs in its code or our library -- which have happened, but +not very often -- a problem in rsasigkey is a problem in GMP.</pre> + +<p>See the next question for how to deal with GMP errors.</p> + +<h3><a name="sig4">!Pluto failure!: ... exited with ... signal 4</a></h3> + +<p>Pluto has died. Signal 4 is SIGILL, illegal instruction.</p> + +<p>The most likely cause is that your <a href="glossary.html#GMP">GMP</a> +(GNU multi-precision) library is compiled for a different processor than what +you are running on. Pluto uses that library for its public key +calculations.</p> + +<p>Try getting the GMP sources and recompile for your processor type. Most +Linux distributions will include this source, or you can download it from the +<a href="http://www.swox.com/gmp/">GMP home page</a>.</p> + +<h3><a name="econnrefused">ECONNREFUSED error message</a></h3> + +<p>From John Denker, on the mailing list:</p> +<pre>1) The log message + some IKE message we sent has been rejected with + ECONNREFUSED (kernel supplied no details) +is much more suitable than the previous version. Thanks. + +2) Minor suggestion for further improvement: it might be worth mentioning +that the command + tcpdump -i eth1 icmp[0] != 8 and icmp[0] != 0 +is useful for tracking down the details in question. We shouldn't expect +all IPsec users to figure that out on their own. The log message might +even provide a hint as to where to look in the docs.</pre> + +<p>Reply From Pluto developer Hugh Redelmeier</p> +<pre>Good idea. + +I've added a bit pluto(8)'s BUGS section along these lines. +I didn't have the heart to lengthen this message.</pre> + +<h3><a name="no_eroute">klips_debug: ... no eroute!</a></h3> + +<p>This message means <a href="glossary.html#KLIPS">KLIPS</a> has received a +packet for which no IPsec tunnel has been defined.</p> + +<p>Here is a more detailed duscussion from the team's tech support person +Claudia Schmeing, responding to a query on the mailing list:</p> +<pre>> Why ipsec reports no eroute! ???? IP Masq... is disabled. + +In general, more information is required so that people on the list may +give you informed input. See doc/prob.report.</pre> + +<p>The document she refers to has since been replaced by a <a +href="trouble.html#prob.report">section</a> of the troubleshooting +document.</p> +<pre>However, I can make some general comments on this type of error. + +This error usually looks something like this (clipped from an archived +message): + +> ttl:64 proto:1 chk:45459 saddr:192.168.1.2 daddr:192.168.100.1 +> ... klips_debug:ipsec_findroute: 192.168.1.2->192.168.100.1 +> ... klips_debug:rj_match: * See if we match exactly as a host destination +> ... klips_debug:rj_match: ** try to match a leaf, t=0xc1a260b0 +> ... klips_debug:rj_match: *** start searching up the tree, t=0xc1a260b0 +> ... klips_debug:rj_match: **** t=0xc1a260c8 +> ... klips_debug:rj_match: **** t=0xc1fe5960 +> ... klips_debug:rj_match: ***** not found. +> ... klips_debug:ipsec_tunnel_start_xmit: Original head/tailroom: 2, 28 +> ... klips_debug:ipsec_tunnel_start_xmit: no eroute!: ts=47.3030, dropping. + + +What does this mean? +- -------------------- + +"eroute" stands for "extended route", and is a special type of route +internal to Linux FreeS/WAN. For more information about this type of route, +see the section of man ipsec_auto on ipsec auto --route. + +"no eroute!" here means, roughly, that Linux FreeS/WAN cannot find an +appropriate tunnel that should have delivered this packet. Linux +FreeS/WAN therefore drops the packet, with the message "no eroute! ... +dropping", on the assumption that this packet is not a legitimate +transmission through a properly constructed tunnel. + + +How does this situation come about? +- ----------------------------------- + +Linux FreeS/WAN has a number of connection descriptions defined in +ipsec.conf. These must be successfully brought "up" to form actual tunnels. +(see doc/setup.html's step 15, man ipsec.conf and man ipsec_auto +for details). + +Such connections are often specific to the endpoints' IPs. However, in +some cases they may be more general, for example in the case of +Road Warriors where left or right is the special value %any. + +When Linux FreeS/WAN receives a packet, it verifies that the packet has +come through a legitimate channel, by checking that there is an +appropriate tunnel through which this packet might legitimately have +arrived. This is the process we see above. + +First, it checks for an eroute that exactly matches the packet. In the +example above, we see it checking for a route that begins at 192.168.1.2 +and ends at 192.168.100.1. This search favours the most specific match that +would apply to the route between these IPs. So, if there is a connection +description exactly matching these IPs, the search will end there. If not, +the code will search for a more general description matching the IPs. +If there is no match, either specific or general, the packet will be +dropped, as we see, above. + +Unless you are working with Road Warriors, only the first, specific part +of the matching process is likely to be relevant to you. + + +"But I defined the tunnel, and it came up, why do I have this error?" +- --------------------------------------------------------------------- + +One of the most common causes of this error is failure to specify enough +connection descriptions to cover all needed tunnels between any two +gateways and their respective subnets. As you have noticed, troubleshooting +this error may be complicated by the use of IP Masq. However, this error is +not limited to cases where IP Masq is used. + +See doc/configuration.html#multitunnel for a detailed example of the +solution to this type of problem.</pre> + +<p>The documentation section she refers to is now <a +href="adv_config.html#multitunnel">here</a>.</p> + +<h3><a name="SAused">... trouble writing to /dev/ipsec ... SA already in +use</a></h3> + +<p>This error message occurs when two manual connections are set up with the +same SPI value. </p> + +<p>See the FAQ for <a href="#spi_error">One manual connection works, but +second one fails</a>.</p> + +<h3><a name="ignore">... ignoring ... payload</a></h3> + +<p>This message is harmless. The IKE protocol provides for a number of +optional messages types:</p> +<ul> + <li>delete SA</li> + <li>initial contact</li> + <li>vendor ID</li> + <li>...</li> +</ul> + +<p>An implementation is never required to send these, but they are allowed +to. The receiver is not required to do anything with them. FreeS/WAN ignores +them, but notifies you via the logs.</p> + +<p>For the "ignoring delete SA Payload" message, see also our discussion of +cleaning up <a href="#deadtunnel">dead tunnels</a>.</p> + +<h3><a name="unknown_rightcert">unknown parameter name "rightcert"</a></h3> + +<P>This message can appear when you've upgraded an X.509-enabled +Linux FreeS/WAN with a vanilla Linux FreeS/WAN. To use your X.509 configs +you will need to overwrite the new install with +<A HREF="http://www.freeswan.ca">Super FreeS/WAN</A>, or add the +<A HREF="http://www.strongsec.ca/freeswan">X.509 patch</A> by hand. +</P> + +<h2><a name="spam">Why don't you restrict the mailing lists to reduce +spam?</a></h2> + +<p>As a matter of policy, some of our <a href="mail.html">mailing lists</a> +need to be open to non-subscribers. Project management feel strongly that +maintaining this openness is more important than blocking spam.</p> +<ul> + <li>Users should be able to get help or report bugs without + subscribing.</li> + <li>Even a user who is subscribed may not have access to his or her + subscribed account when he or she needs help, miles from home base in the + middle of setting up a client's gateway.</li> + <li>There is arguably a legal requirement for this policy. A US resident or + citizen could be charged under munitions export laws for providing + technical assistance to a foreign cryptographic project. Such a charge + would be more easily defended if the discussion takes place in public, on + an open list.</li> +</ul> + +<p>This has been discussed several times at some length on the list. See the +<a href="mail.html#archive">list archives</a>. Bringing the topic up again is +unlikely to be useful. Please don't. Or at the very least, please don't +without reading the archives and being certain that whatever you are about to +suggest has not yet been discussed.</p> + +<p>Project technical lead Henry Spencer summarised one discussion:</p> + +<blockquote> + For the third and last time: this list *will* *not* do address-based + filtering. This is a policy decision, not an implementation problem. The + decision is final, and is not open to discussion. This needs to be + communicated better to people, and steps are being taken to do +that.</blockquote> + +<p>Adding this FAQ section is one of the steps he refers to.</p> + +<p>You have various options other than just putting up with the spam, +filtering it yourself, or unsubscribing:</p> +<ul> + <li>subscribe only to one or both of our lists with restricted posting + rules: + <ul> + <li><a + href="mailto:briefs@lists.freeswan.org?body=subscribe">briefs</a>, + weekly list summaries</li> + <li><a + href="mailto:announce@lists.freeswan.org?body=subscribe">announce</a>, + project-related announcements</li> + </ul> + </li> + <li>read the other lists via the <a + href="mail.html#archive">archives</a></li> +</ul> + +<p>A number of tools are available to filter mail.</p> +<ul> + <li>Many mail readers include some filtering capability.</li> + <li>Many Linux distributions include <a + href="http://www.procmail.org/">procmail(8)</a> for server-side + filtering.</li> + <li>The <a href="http://www.spambouncer.org/">Spam Bouncer</a> is a set of + procmail(8) filters designed to combat spam.</li> + <li>Roaring Penguin have a <a + href="http://www.roaringpenguin.com/mimedefang/">MIME defanger</a> that + removes potentially dangerous attachments.</li> +</ul> + +<p>If you use your ISP's mail server rather than running your own, consider +suggesting to the ISP that they tag suspected spam as <a +href="http://www.msen.com/1997/spam.html#SUSPECTED">this ISP</a> does. They +could just refuse mail from dubious sources, but that is tricky and runs some +risk of losing valuable mail or senselessly annoying senders and their +admins. However, they can safely tag and deliver dubious mail. The tags can +greatly assist your filtering.</p> + +<p>For information on tracking down spammers, see these <a +href="http://www.rahul.net/falk/#howtos">HowTos</a>, or the <a +href="http://www.sputum.com/index2.html">Sputum</a> site. Sputum have a Linux +anti-spam screensaver available for download.</p> + +<p>Here is a more detailed message from Henry:</p> +<pre>On Mon, 15 Jan 2001, Jay Vaughan wrote: +> I know I'm flogging a dead horse here, but I'm curious as to the reasons for +> an aversion for a subscriber-only mailing list? + +Once again: for legal reasons, it is important that discussions of these +things be held in a public place -- the list -- and we do not want to +force people to subscribe to the list just to ask one question, because +that may be more than merely inconvenient for them. There are also real +difficulties with people who are temporarily forced to use alternate +addresses; that is precisely the time when they may be most in need of +help, yet a subscribers-only policy shuts them out. + +These issues do not apply to most mailing lists, but for a list that is +(necessarily) the primary user support route for a crypto package, they +are very important. This is *not* an ordinary mailing list; it has to +function under awkward constraints that make various simplistic solutions +inapplicable or undesirable. + +> We're *ALL* sick of hearing about list management problems, not just you +> old-timers, so why don't you DO SOMETHING EFFECTIVE ABOUT IT... + +Because it's a lot harder than it looks, and many existing "solutions" +have problems when examined closely. + +> A suggestion for you, based on 10 years of experience with management of my +> own mailing lists would be to use mailman, which includes pretty much every +> feature under the sun that you guys need and want, plus some. The URL for +> mailman... + +I assure you, we're aware of mailman. Along with a whole bunch of others, +including some you almost certainly have never heard of (I hadn't!). + +> As for the argument that the list shouldn't be configured to enforce +> subscription - I contend that it *SHOULD* AT LEAST require manual address +> verification in order for posts to be redirected. + +You do realize, I hope, that interposing such a manual step might cause +your government to decide that this is not truly a public forum, and thus +you could go to jail if you don't get approval from them before mailing to +it? If you think this sounds irrational, your government is noted for +making irrational decisions in this area; we can't assume that they will +suddenly start being sensible. See above about awkward constraints. You +may be willing to take the risk, but we can't, in good conscience, insist +that all users with problems do so. + + Henry Spencer + henry@spsystems.net</pre> + +<p>and a message on the topic from project leader John Gilmore:</p> +<pre>Subject: Re: The linux-ipsec list's topic + Date: Sat, 30 Dec 2000 + From: John Gilmore <gnu@toad.com> + +I'll post this single message, once only, in this discussion, and then +not burden the list with any further off-topic messages. I encourage +everyone on the list to restrain themself from posting ANY off-topic +messages to the linux-ipsec list. + +The topic of the linux-ipsec mailing list is the FreeS/WAN software. + +I frequently see "discussions about spam on a list" overwhelm the +volume of "actual spam" on a list. BOTH kinds of messages are +off-topic messages. Twenty anti-spam messages take just as long to +detect and discard as twenty spam messages. + +The Linux-ipsec list encourages on-topic messages from people who have +not joined the list itself. We will not censor messages to the list +based on where they originate, or what return address they contain. +In other words, non-subscribers ARE allowed to post, and this will not +change. My own valid contributions have been rejected out-of-hand by +too many other mailing lists for me to want to impose that censorship +on anybody else's contributions. And every day I see the damage that +anti-spam zeal is causing in many other ways; that zeal is far more +damaging to the culture of the Internet than the nuisance of spam. + +In general, it is the responsibility of recipients to filter, +prioritize, or otherwise manage the handling of email that comes to +them. It is not the responsibility of the rest of the Internet +community to refrain from sending messages to recipients that they +might not want to see. If your software infrastructure for managing +your incoming email is insufficient, then improve it. If you think +the signal-to-noise ratio on linux-ipsec is too poor, then please +unsubscribe. But don't further increase the noise by posting to the +linux-ipsec list about those topics. + + John Gilmore + founder & sponsor, FreeS/WAN project</pre> +</body> +</html> diff --git a/doc/src/firewall.html b/doc/src/firewall.html new file mode 100644 index 000000000..5051b458d --- /dev/null +++ b/doc/src/firewall.html @@ -0,0 +1,895 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN and firewalls</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, firewall, ipchains, iptables"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: firewall.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="firewall">FreeS/WAN and firewalls</a></h1> + +<p>FreeS/WAN, or other IPsec implementations, frequently run on gateway +machines, the same machines running firewall or packet filtering code. This +document discusses the relation between the two.</p> + +<p>The firewall code in 2.4 and later kernels is called Netfilter. The +user-space utility to manage a firewall is iptables(8). See the <a +href="http://netfilter.samba.org">netfilter/iptables web site</a> for +details.</p> + +<h2><a name="filters">Filtering rules for IPsec packets</a></h2> + +<p>The basic constraint is that <strong>an IPsec gateway must have packet +filters that allow IPsec packets</strong>, at least when talking to other +IPsec gateways:</p> +<ul> + <li>UDP port 500 for <a href="glossary.html#IKE">IKE</a> negotiations</li> + <li>protocol 50 if you use <a href="glossary.html#ESP">ESP</a> encryption + and/or authentication (the typical case)</li> + <li>protocol 51 if you use <a href="glossary.html#AH">AH</a> packet-level + authentication</li> +</ul> + +<p>Your gateway and the other IPsec gateways it communicates with must be +able to exchange these packets for IPsec to work. Firewall rules must allow +UDP 500 and at least one of <a href="glossary.html#AH">AH</a> or +<a href="glossary.html#ESP">ESP</a> on +the interface that communicates with the other gateway.</p> + +<p>For nearly all FreeS/WAN applications, you must allow UDP port 500 and the +ESP protocol.</p> + +<p>There are two ways to set this up:</p> +<dl> + <dt>easier but less flexible</dt> + <dd>Just set up your firewall scripts at boot time to allow IPsec packets + to and from your gateway. Let FreeS/WAN reject any bogus packets.</dd> + <dt>more work, giving you more precise control</dt> + <dd>Have the <a href="manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</a> + daemon call scripts to adjust firewall rules dynamically as required. + This is done by naming the scripts in the <a + href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> variables + <var>prepluto=</var>, <var>postpluto=</var>, <var>leftupdown=</var> and + <var>rightupdown=</var>.</dd> +</dl> + +<p>Both methods are described in more detail below.</p> + +<h2><a name="examplefw">Firewall configuration at boot</a></h2> + +<p>It is possible to set up both firewalling and IPsec with appropriate +scripts at boot and then not use <var>leftupdown=</var> and +<var>rightupdown=</var>, or use them only for simple up and down +operations.</p> + +<p>Basically, the technique is</p> +<ul> + <li>allow IPsec packets (typically, IKE on UDP port 500 plus ESP, protocol + 50) + <ul> + <li>incoming, if the destination address is your gateway (and + optionally, only from known senders)</li> + <li>outgoing, with the from address of your gateway (and optionally, + only to known receivers)</li> + </ul> + </li> + <li>let <a href="glossary.html#Pluto">Pluto</a> deal with IKE</li> + <li>let <a href="glossary.html#KLIPS">KLIPS</a> deal with ESP</li> +</ul> + +<p>Since Pluto authenticates its partners during the negotiation, and KLIPS +drops packets for which no tunnel has been negotiated, this may be all you +need.</p> + +<h3><a name="simple.rules">A simple set of rules</a></h3> + +<p>In simple cases, you need only a few rules, as in this example:</p> +<pre># allow IPsec +# +# IKE negotiations +iptables -I INPUT -p udp --sport 500 --dport 500 -j ACCEPT +iptables -I OUTPUT -p udp --sport 500 --dport 500 -j ACCEPT +# ESP encryption and authentication +iptables -I INPUT -p 50 -j ACCEPT +iptables -I OUTPUT -p 50 -j ACCEPT +</pre> + +<P>This should be all you need to allow IPsec through <var>lokkit</var>, +which ships with Red Hat 9, on its medium security setting. +Once you've tweaked to your satisfaction, save your active rule set with:</P> +<PRE>service iptables save</PRE> + +<h3><a name="complex.rules">Other rules</a></h3> +You can add additional rules, or modify existing ones, to work with IPsec and +with your network and policies. We give a some examples in this section. + +<p>However, while it is certainly possible to create an elaborate set of +rules yourself (please let us know via the <a href="mail.html">mailing +list</a> if you do), it may be both easier and more secure to use a set which +has already been published and tested.</p> + +<p>The published rule sets we know of are described in the <a +href="#rules.pub">next section</a>.</p> + +<h4>Adding additional rules</h4> +If necessary, you can add additional rules to: +<dl> + <dt>reject IPsec packets that are not to or from known gateways</dt> + <dd>This possibility is discussed in more detail <a + href="#unknowngate">later</a></dd> + <dt>allow systems behind your gateway to build IPsec tunnels that pass + through the gateway</dt> + <dd>This possibility is discussed in more detail <a + href="#through">later</a></dd> + <dt>filter incoming packets emerging from KLIPS.</dt> + <dd>Firewall rules can recognise packets emerging from IPsec. They are + marked as arriving on an interface such as <var>ipsec0</var>, rather + than <var>eth0</var>, <var>ppp0</var> or whatever.</dd> +</dl> + +<p>It is therefore reasonably straightforward to filter these packets in +whatever way suits your situation.</p> + +<h4>Modifying existing rules</h4> + +<p>In some cases rules that work fine before you add IPsec may require +modification to work with IPsec.</p> + +<p>This is especially likely for rules that deal with interfaces on the +Internet side of your system. IPsec adds a new interface; often the rules +must change to take account of that.</p> + +<p>For example, consider the rules given in <a +href="http://www.netfilter.org/documentation/HOWTO//packet-filtering-HOWTO-5.html">this +section</a> of the Netfilter documentation:</p> +<pre>Most people just have a single PPP connection to the Internet, and don't +want anyone coming back into their network, or the firewall: + + ## Insert connection-tracking modules (not needed if built into kernel). + # insmod ip_conntrack + # insmod ip_conntrack_ftp + + ## Create chain which blocks new connections, except if coming from inside. + # iptables -N block + # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT + # iptables -A block -m state --state NEW -i ! ppp0 -j ACCEPT + # iptables -A block -j DROP + + ## Jump to that chain from INPUT and FORWARD chains. + # iptables -A INPUT -j block + # iptables -A FORWARD -j block</pre> + +<p>On an IPsec gateway, those rules may need to be modified. The above allows +new connections from <em>anywhere except ppp0</em>. That means new +connections from ipsec0 are allowed.</p> + +<p>Do you want to allow anyone who can establish an IPsec connection to your +gateway to initiate TCP connections to any service on your network? Almost +certainly not if you are using opportunistic encryption. Quite possibly not +even if you have only explicitly configured connections.</p> + +<p>To disallow incoming connections from ipsec0, change the middle section +above to:</p> +<pre> ## Create chain which blocks new connections, except if coming from inside. + # iptables -N block + # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT + # iptables -A block -m state --state NEW -i ppp+ -j DROP + # iptables -A block -m state --state NEW -i ipsec+ -j DROP + # iptables -A block -m state --state NEW -i -j ACCEPT + # iptables -A block -j DROP</pre> + +<p>The original rules accepted NEW connections from anywhere except ppp0. +This version drops NEW connections from any PPP interface (ppp+) and from any +ipsec interface (ipsec+), then accepts the survivors.</p> + +<p>Of course, these are only examples. You will need to adapt them to your +own situation.</p> + +<h3><a name="rules.pub">Published rule sets</a></h3> + +<p>Several sets of firewall rules that work with FreeS/WAN are available.</p> + +<h4><a name="Ranch.trinity">Scripts based on Ranch's work</a></h4> + +<p>One user, Rob Hutton, posted his boot time scripts to the mailing list, +and we included them in previous versions of this documentation. They are +still available from our <a +href="http://www.freeswan.org/freeswan_trees/freeswan-1.5/doc/firewall.html#examplefw">web +site</a>. However, they were for an earlier FreeS/WAN version so we no longer +recommend them. Also, they had some bugs. See this <a +href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/04/msg00316.html">message</a>.</p> + +<p>Those scripts were based on David Ranch's scripts for his "Trinity OS" for +setting up a secure Linux. Check his <a +href="http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html">home +page</a> for the latest version and for information on his <a +href="biblio.html#ranch">book</a> on securing Linux. If you are going to base +your firewalling on Ranch's scripts, we recommend using his latest version, +and sending him any IPsec modifications you make for incorporation into later +versions.</p> + +<h4><a name="seawall">The Seattle firewall</a></h4> + +<p>We have had several mailing lists reports of good results using FreeS/WAN +with Seawall (the Seattle Firewall). See that project's <a +href="http://seawall.sourceforge.net/">home page</a> on Sourceforge.</p> + +<h4><a name="rcf">The RCF scripts</a></h4> + +<p>Another set of firewall scripts with IPsec support are the RCF or +rc.firewall scripts. See their <a +href="http://jsmoriss.mvlan.net/linux/rcf.html">home page</a>.</p> + +<h4><a name="asgard">Asgard scripts</a></h4> + +<p><a href="http://heimdall.asgardsrealm.net/linux/firewall/">Asgard's +Realm</a> has set of firewall scripts with FreeS/WAN support, for 2.4 kernels +and iptables.</p> + +<h4><a name="user.scripts">User scripts from the mailing list</a></h4> + +<p>One user gave considerable detail on his scripts, including supporting <a +href="glossary.html#IPX">IPX</a> through the tunnel. His message was too long +to conveniently be quoted here, so I've put it in a <a +href="user_examples.html">separate file</a>.</p> + +<h2><a name="updown">Calling firewall scripts, named in ipsec.conf(5)</a></h2> + +<p>The <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> configuration +file has three pairs of parameters used to specify an interface between +FreeS/WAN and firewalling code.</p> + +<p>Note that using these is not required if you have a static firewall setup. +In that case, you just set your firewall up at boot time (in a way that +permits the IPsec connections you want) and do not change it thereafter. Omit +all the FreeS/WAN firewall parameters and FreeS/WAN will not attempt to +adjust firewall rules at all. See <a href="#examplefw">above</a> for some +information on appropriate scripts.</p> + +<p>However, if you want your firewall rules to change when IPsec connections +change, then you need to use these parameters.</p> + +<h3><a name="pre_post">Scripts called at IPsec start and stop</a></h3> + +<p>One pair of parmeters are set in the <var>config setup</var> section of +the <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file and affect +all connections:</p> +<dl> + <dt>prepluto=</dt> + <dd>script to be called before <a + href="manpage.d/ipsec_pluto.8.html">pluto(8)</a> IKE daemon is + started.</dd> + <dt>postpluto=</dt> + <dd>script to be called after <a + href="manpage.d/ipsec_pluto.8.html">pluto(8)</a> IKE daemon is + stopped.</dd> +</dl> +These parameters allow you to change firewall parameters whenever IPsec is +started or stopped. + +<p>They can also be used in other ways. For example, you might have +<var>prepluto</var> add a module to your kernel for the secure network +interface or make a dialup connection, and then have <var>postpluto</var> +remove the module or take the connection down.</p> + +<h3><a name="up_down">Scripts called at connection up and down</a></h3> + +<p>The other parameters are set in connection descriptions. They can be set +in individual connection descriptions, and could even call different scripts +for each connection for maximum flexibility. In most applications, however, +it makes sense to use only one script and to call it from <var>conn +%default</var> section so that it applies to all connections.</p> + +<p>You can:</p> +<dl> + <dt><strong>either</strong></dt> + <dd>set <var>leftfirewall=yes</var> or <var>rightfirewall=yes</var> to + use our supplied default script</dd> + <dt><strong>or</strong></dt> + <dd>assign a name in a <var>leftupdown=</var> or <var>rightupdown=</var> + line to use your own script</dd> +</dl> + +<p>Note that <strong>only one of these should be used</strong>. You cannot +sensibly use both. Since <strong>our default script is obsolete</strong> +(designed for firewalls using <var>ipfwadm(8)</var> on 2.0 kernels), most +users who need this service will <strong>need to write a custom +script</strong>.</p> + +<h4><a name="fw.default">The default script</a></h4> + +<p>We supply a default script named <var>_updown</var>.</p> +<dl> + <dt>leftfirewall=</dt> + <dd></dd> + <dt>rightfirewall=</dt> + <dd>indicates that the gateway is doing firewalling and that <a + href="manpage.d/ipsec_pluto.8.html">pluto(8)</a> should poke holes in + the firewall as required.</dd> +</dl> + +<p>Set these to <var>yes</var> and Pluto will call our default script +<var>_updown</var> with appropriate arguments whenever it:</p> +<ul> + <li>starts or stops IPsec services</li> + <li>brings a connection up or down</li> +</ul> + +<p>The supplied default <var>_updown</var> script is appropriate for simple +cases using the <var>ipfwadm(8)</var> firewalling package.</p> + +<h4><a name="userscript">User-written scripts</a></h4> + +<p>You can also write your own script and have Pluto call it. Just put the +script's name in one of these <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> lines:</p> +<dl> + <dt>leftupdown=</dt> + <dd></dd> + <dt>rightupdown=</dt> + <dd>specifies a script to call instead of our default script + <var>_updown</var>.</dd> +</dl> + +<p>Your script should take the same arguments and use the same environment +variables as <var>_updown</var>. See the "updown command" section of the <a +href="manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</a> man page for +details.</p> + +<p>Note that <strong>you should not modify our _updown script in +place</strong>. If you did that, then upgraded FreeS/WAN, the upgrade would +install a new default script, overwriting your changes.</p> + +<h3><a name="ipchains.script">Scripts for ipchains or iptables</a></h3> + +<p>Our <var>_updown</var> is for firewalls using <var>ipfwadm(8)</var>, the +firewall code for the 2.0 series of Linux kernels. If you are using the more +recent packages <var>ipchains(8)</var> (for 2.2 kernels) or +<var>iptables(8)</var> (2.4 kernels), then you must do one of:</p> +<ul> + <li>use static firewall rules which are set up at boot time as described <a + href="#examplefw">above</a> and do not need to be changed by Pluto</li> + <li>limit yourself to ipchains(8)'s ipfwadm(8) emulation mode in order to + use our script</li> + <li>write your own script and call it with <var>leftupdown</var> and + <var>rightupdown</var>.</li> +</ul> + +<p>You can write a script to do whatever you need with firewalling. Specify +its name in a <var>[left|right]updown=</var> parameter in <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> and Pluto will +automatically call it for you.</p> + +<p>The arguments Pluto passes such a script are the same ones it passes to +our default _updown script, so the best way to build yours is to copy ours +and modify the copy.</p> + +<p>Note, however, that <strong>you should not modify our _updown script in +place</strong>. If you did that, then upgraded FreeS/WAN, the upgrade would +install a new default script, overwriting your changes.</p> + +<h2><a name="NAT">A complication: IPsec vs. NAT</a></h2> + +<p><a href="glossary.html#NAT.gloss">Network Address Translation</a>, also +known as IP masquerading, is a method of allocating IP addresses dynamically, +typically in circumstances where the total number of machines which need to +access the Internet exceeds the supply of IP addresses.</p> + +<p>Any attempt to perform NAT operations on IPsec packets <em>between the +IPsec gateways</em> creates a basic conflict:</p> +<ul> + <li>IPsec wants to authenticate packets and ensure they are unaltered on a + gateway-to-gateway basis</li> + <li>NAT rewrites packet headers as they go by</li> + <li>IPsec authentication fails if packets are rewritten anywhere between + the IPsec gateways</li> +</ul> + +<p>For <a href="glossary.html#AH">AH</a>, which authenticates parts of the +packet header including source and destination IP addresses, this is fatal. +If NAT changes those fields, AH authentication fails.</p> + +<p>For <a href="glossary.html#IKE">IKE</a> and <a +href="glossary.html#ESP">ESP</a> it is not necessarily fatal, but is +certainly an unwelcome complication.</p> + +<h3><a name="nat_ok">NAT on or behind the IPsec gateway works</a></h3> + +<p>This problem can be avoided by having the masquerading take place <em>on +or behind</em> the IPsec gateway.</p> + +<p>This can be done physically with two machines, one physically behind the +other. A picture, using SG to indicate IPsec <strong>S</strong>ecurity +<strong>G</strong>ateways, is:</p> +<pre> clients --- NAT ----- SG ---------- SG + two machines</pre> + +<p>In this configuration, the actual client addresses need not be given in +the <var>leftsubnet=</var> parameter of the FreeS/WAN connection description. +The security gateway just delivers packets to the NAT box; it needs only that +machine's address. What that machine does with them does not affect +FreeS/WAN.</p> + +<p>A more common setup has one machine performing both functions:</p> +<pre> clients ----- NAT/SG ---------------SG + one machine</pre> + +<p>Here you have a choice of techniques depending on whether you want to make +your client subnet visible to clients on the other end:</p> +<ul> + <li>If you want the single gateway to behave like the two shown above, with + your clients hidden behind the NAT, then omit the <var>leftsubnet=</var> + parameter. It then defaults to the gateway address. Clients on the other + end then talk via the tunnel only to your gateway. The gateway takes + packets emerging from the tunnel, applies normal masquerading, and + forwards them to clients.</li> + <li>If you want to make your client machines visible, then give the client + subnet addresses as the <var>leftsubnet=</var> parameter in the + connection description and + <dl> + <dt>either</dt> + <dd>set <var>leftfirewall=yes</var> to use the default + <var>updown</var> script</dd> + <dt>or</dt> + <dd>use your own script by giving its name in a + <var>leftupdown=</var> parameter</dd> + </dl> + These scripts are described in their own <a href="#updown">section</a>. + <p>In this case, no masquerading is done. Packets to or from the client + subnet are encrypted or decrypted without any change to their client + subnet addresses, although of course the encapsulating packets use + gateway addresses in their headers. Clients behind the right security + gateway see a route via that gateway to the left subnet.</p> + </li> +</ul> + +<h3><a name="nat_bad">NAT between gateways is problematic</a></h3> + +<p>We recommend not trying to build IPsec connections which pass through a +NAT machine. This setup poses problems:</p> +<pre> clients --- SG --- NAT ---------- SG</pre> + +<p>If you must try it, some references are:</p> +<ul> + <li>Jean_Francois Nadeau's document on doing <a + href="http://jixen.tripod.com/#NATed gateways">IPsec behind NAT</a></li> + <li><a href="web.html#VPN.masq">VPN masquerade patches</a> to make a Linux + NAT box handle IPsec packets correctly</li> +</ul> + +<h3><a name="NAT.ref">Other references on NAT and IPsec</a></h3> + +<p>Other documents which may be relevant include:</p> +<ul> + <li>an Internet Draft on <a + href="http://search.ietf.org/internet-drafts/draft-aboba-nat-ipsec-04.txt">IPsec + and NAT</a> which may eventually evolve into a standard solution for this + problem.</li> + <li>an informational <a + href="http://www.cis.ohio-state.edu/rfc/rfc2709.txt">RFC</a>, + <cite>Security Model with Tunnel-mode IPsec for NAT Domains</cite>.</li> + <li>an <a + href="http://www.cisco.com/warp/public/759/ipj_3-4/ipj_3-4_nat.html">article</a> + in Cisco's <cite>Internet Protocol Journal</cite></li> +</ul> + +<h2><a name="complications">Other complications</a></h2> + +<p>Of course simply allowing UDP 500 and ESP packets is not the whole story. +Various other issues arise in making IPsec and packet filters co-exist and +even co-operate. Some of them are summarised below.</p> + +<h3><a name="through">IPsec <em>through</em></a> the gateway</h3> + +<p>Basic IPsec packet filtering rules deal only with packets addressed to or +sent from your IPsec gateway.</p> + +<p>It is a separate policy decision whether to permit such packets to pass +through the gateway so that client machines can build end-to-end IPsec +tunnels of their own. This may not be practical if you are using <a +href="#NAT">NAT (IP masquerade)</a> on your gateway, and may conflict with +some corporate security policies.</p> + +<p>Where possible, allowing this is almost certainly a good idea. Using IPsec +on an end-to-end basis is more secure than gateway-to-gateway.</p> + +<p>Doing it is quite simple. You just need firewall rules that allow UDP port +500 and protocols 50 and 51 to pass through your gateway. If you wish, you +can of course restrict this to certain hosts.</p> + +<h3><a name="ipsec_only">Preventing non-IPsec traffic</a></h3> +You can also filter <em>everything but</em> UDP port 500 and ESP or AH to +restrict traffic to IPsec only, either for anyone communicating with your +host or just for specific partners. + +<p>One application of this is for the telecommuter who might have:</p> +<pre> Sunset==========West------------------East ================= firewall --- the Internet + home network untrusted net corporate network</pre> + +<p>The subnet on the right is 0.0.0.0/0, the whole Internet. The West gateway +is set up so that it allows only IPsec packets to East in or out.</p> + +<p>This configuration is used in AT&T Research's network. For details, +see the <a href="intro.html#applied">papers</a> links in our introduction.</p> + +<p>Another application would be to set up firewall rules so that an internal +machine, such as an employees-only web server, could not talk to the outside +world except via specific IPsec tunnels.</p> + +<h3><a name="unknowngate">Filtering packets from unknown gateways</a></h3> + +<p>It is possible to use firewall rules to restrict UDP 500, ESP and AH +packets so that these packets are accepted only from known gateways. This is +not strictly necessary since FreeS/WAN will discard packets from unknown +gateways. You might, however, want to do it for any of a number of reasons. +For example:</p> +<ul> + <li>Arguably, "belt and suspenders" is the sensible approach to security. + If you can block a potential attack in two ways, use both. The only + question is whether to look for a third way after implementing the first + two.</li> + <li>Some admins may prefer to use the firewall code this way because they + prefer firewall logging to FreeS/WAN's logging.</li> + <li>You may need it to implement your security policy. Consider an employee + working at home, and a policy that says traffic from the home system to + the Internet at large must go first via IPsec to the corporate LAN and + then out to the Internet via the corporate firewall. One way to do that + is to make <var>ipsec0</var> the default route on the home gateway and + provide exceptions only for UDP 500 and ESP to the corporate gateway. + Everything else is then routed via the tunnel to the corporate + gateway.</li> +</ul> + +<p>It is not possible to use only static firewall rules for this filtering if +you do not know the other gateways' IP addresses in advance, for example if +you have "road warriors" who may connect from a different address each time +or if want to do <a href="glossary.html#carpediem">opportunistic +encryption</a> to arbitrary gateways. In these cases, you can accept UDP 500 +IKE packets from anywhere, then use the <a href="#updown">updown</a> script +feature of <a href="manpage.d/ipsec_pluto.8.html">pluto(8)</a> to dynamically +adjust firewalling for each negotiated tunnel.</p> + +<p>Firewall packet filtering does not much reduce the risk of a <a +href="glossary.html#DOS">denial of service attack</a> on FreeS/WAN. The +firewall can drop packets from unknown gateways, but KLIPS does that quite +efficiently anyway, so you gain little. The firewall cannot drop otherwise +legitmate packets that fail KLIPS authentication, so it cannot protect +against an attack designed to exhaust resources by making FreeS/WAN perform +many expensive authentication operations.</p> + +<p>In summary, firewall filtering of IPsec packets from unknown gateways is +possible but not strictly necessary.</p> + +<h2><a name="otherfilter">Other packet filters</a></h2> + +<p>When the IPsec gateway is also acting as your firewall, other packet +filtering rules will be in play. In general, those are outside the scope of +this document. See our <a href="web.html#firewall.linux">Linux firewall +links</a> for information. There are a few types of packet, however, which +can affect the operation of FreeS/WAN or of diagnostic tools commonly used +with it. These are discussed below.</p> + +<h3><a name="ICMP">ICMP filtering</a></h3> + +<p><a href="glossary.html#ICMP.gloss">ICMP</a> is the +<strong>I</strong>nternet <strong>C</strong>ontrol <strong>M</strong>essage +<strong>P</strong>rotocol. It is used for messages between IP implementations +themselves, whereas IP used is used between the clients of those +implementations. ICMP is, unsurprisingly, used for control messages. For +example, it is used to notify a sender that a desination is not reachable, or +to tell a router to reroute certain packets elsewhere.</p> + +<p>ICMP handling is tricky for firewalls.</p> +<ul> + <li>You definitely want some ICMP messages to get through; things won't + work without them. For example, your clients need to know if some + destination they ask for is unreachable.</li> + <li>On the other hand, you do equally definitely do not want untrusted folk + sending arbitrary control messages to your machines. Imagine what someone + moderately clever and moderately malicious could do to you, given control + of your network's routing.</li> +</ul> + +<p>ICMP does not use ports. Messages are distinguished by a "message type" +field and, for some types, by an additional "code" field. The definitive list +of types and codes is on the <a href="http://www.iana.org">IANA</a> site.</p> + +<p>One expert uses this definition for ICMP message types to be dropped at +the firewall.</p> +<pre># ICMP types which lack socially redeeming value. +# 5 Redirect +# 9 Router Advertisement +# 10 Router Selection +# 15 Information Request +# 16 Information Reply +# 17 Address Mask Request +# 18 Address Mask Reply + +badicmp='5 9 10 15 16 17 18'</pre> + +<p>A more conservative approach would be to make a list of allowed types and +drop everything else.</p> + +<p>Whichever way you do it, your ICMP filtering rules on a FreeS/WAN gateway +should allow at least the following ICMP packet types:</p> +<dl> + <dt>echo (type 8)</dt> + <dd></dd> + <dt>echo reply (type 0)</dt> + <dd>These are used by ping(1). We recommend allowing both types through + the tunnel and to or from your gateway's external interface, since + ping(1) is an essential testing tool. + <p>It is fairly common for firewalls to drop ICMP echo packets + addressed to machines behind the firewall. If that is your policy, + please create an exception for such packets arriving via an IPsec + tunnel, at least during intial testing of those tunnels.</p> + </dd> + <dt>destination unreachable (type 3)</dt> + <dd>This is used, with code 4 (Fragmentation Needed and Don't Fragment + was Set) in the code field, to control <a + href="glossary.html#pathMTU">path MTU discovery</a>. Since IPsec + processing adds headers, enlarges packets and may cause fragmentation, + an IPsec gateway should be able to send and receive these ICMP messages + <strong>on both inside and outside interfaces</strong>.</dd> +</dl> + +<h3><a name="traceroute">UDP packets for traceroute</a></h3> + +<p>The traceroute(1) utility uses UDP port numbers from 33434 to +approximately 33633. Generally, these should be allowed through for +troubleshooting.</p> + +<p>Some firewalls drop these packets to prevent outsiders exploring the +protected network with traceroute(1). If that is your policy, consider +creating an exception for such packets arriving via an IPsec tunnel, at least +during intial testing of those tunnels.</p> + +<h3><a name="l2tp">UDP for L2TP</a></h3> +<p> +Windows 2000 does, and products designed for compatibility with it may, build +<a href="glossary.html#L2TP">L2TP</a> tunnels over IPsec connections. + +<p>For this to work, you must allow UDP protocol 1701 packets coming out of +your tunnels to continue to their destination. You can, and probably should, +block such packets to or from your external interfaces, but allow them from +<var>ipsec0</var>.</p> + +<p>See also our Windows 2000 <a href="interop.html#win2k">interoperation +discussion</a>.</p> + +<h2><a name="packets">How it all works: IPsec packet details</a></h2> + +<p>IPsec uses three main types of packet:</p> +<dl> + <dt><a href="glossary.html#IKE">IKE</a> uses <strong>the UDP protocol and + port 500</strong>.</dt> + <dd>Unless you are using only (less secure, not recommended) manual + keying, you need IKE to negotiate connection parameters, acceptable + algorithms, key sizes and key setup. IKE handles everything required to + set up, rekey, repair or tear down IPsec connections.</dd> + <dt><a href="glossary.html#ESP">ESP</a> is <strong>protocol number + 50</strong></dt> + <dd>This is required for encrypted connections.</dd> + <dt><a href="glossary.html#AH">AH</a> is <strong>protocol number + 51</strong></dt> + <dd>This can be used where only authentication, not encryption, is + required.</dd> +</dl> + +<p>All of those packets should have appropriate IPsec gateway addresses in +both the to and from IP header fields. Firewall rules can check this if you +wish, though it is not strictly necessary. This is discussed in more detail +<a href="#unknowngate">later</a>.</p> + +<p>IPsec processing of incoming packets authenticates them then removes the +ESP or AH header and decrypts if necessary. Successful processing exposes an +inner packet which is then delivered back to the firewall machinery, marked +as having arrived on an <var>ipsec[0-3]</var> interface. Firewall rules can +use that interface label to distinguish these packets from unencrypted +packets which are labelled with the physical interface they arrived on (or +perhaps with a non-IPsec virtual interface such as <var>ppp0</var>).</p> + +<p>One of our users sent a mailing list message with a <a +href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/12/msg00006.html">diagram</a> +of the packet flow.</p> + +<h3><a name="noport">ESP and AH do not have ports</a></h3> + +<p>Some protocols, such as TCP and UDP, have the notion of ports. Others +protocols, including ESP and AH, do not. Quite a few IPsec newcomers have +become confused on this point. There are no ports <em>in</em> the ESP or AH +protocols, and no ports used <em>for</em> them. For these protocols, <em>the +idea of ports is completely irrelevant</em>.</p> + +<h3><a name="header">Header layout</a></h3> + +<p>The protocol numbers for ESP or AH are used in the 'next header' field of +the IP header. On most non-IPsec packets, that field would have one of:</p> +<ul> + <li>1 for ICMP</li> + <li>4 for IP-in-IP encapsulation</li> + <li>6 for TCP</li> + <li>17 for UDP</li> + <li>... or one of about 100 other possibilities listed by <a + href="http://www.iana.org">IANA</a></li> +</ul> + +<p>Each header in the sequence tells what the next header will be. IPsec adds +headers for ESP or AH near the beginning of the sequence. The original +headers are kept and the 'next header' fields adjusted so that all headers +can be correctly interpreted.</p> + +<p>For example, using <strong>[</strong> <strong>]</strong> to indicate data +protected by ESP and unintelligible to an eavesdropper between the +gateways:</p> +<ul> + <li>a simple packet might have only IP and TCP headers with: + <ul> + <li>IP header says next header --> TCP</li> + <li>TCP header port number --> which process to send data to</li> + <li>data</li> + </ul> + </li> + <li>with ESP <a href="glossary.html#transport">transport mode</a> + encapsulation, that packet would have: + <ul> + <li>IP header says next header --> ESP</li> + <li>ESP header <strong>[</strong> says next --> TCP</li> + <li>TCP header port number --> which process to send data to</li> + <li>data <strong>]</strong></li> + </ul> + Note that the IP header is outside ESP protection, visible to an + attacker, and that the final destination must be the gateway.</li> + <li>with ESP in <a href="glossary.html#tunnel">tunnel mode</a>, we might + have: + <ul> + <li>IP header says next header --> ESP</li> + <li>ESP header <strong>[</strong> says next --> IP</li> + <li>IP header says next header --> TCP</li> + <li>TCP header port number --> which process to send data to</li> + <li>data <strong>]</strong></li> + </ul> + Here the inner IP header is protected by ESP, unreadable by an attacker. + Also, the inner header can have a different IP address than the outer IP + header, so the decrypted packet can be routed from the IPsec gateway to a + final destination which may be another machine.</li> +</ul> + +<p>Part of the ESP header itself is encrypted, which is why the +<strong>[</strong> indicating protected data appears in the middle of some +lines above. The next header field of the ESP header is protected. This makes +<a href="glossary.html#traffic">traffic analysis</a> more difficult. The next +header field would tell an eavesdropper whether your packet was UDP to the +gateway, TCP to the gateway, or encapsulated IP. It is better not to give +this information away. A clever attacker may deduce some of it from the +pattern of packet sizes and timings, but we need not make it easy.</p> + +<p>IPsec allows various combinations of these to match local policies, +including combinations that use both AH and ESP headers or that nest multiple +copies of these headers.</p> + +<p>For example, suppose my employer has an IPsec VPN running between two +offices so all packets travelling between the gateways for those offices are +encrypted. If gateway policies allow it (The admins could block UDP 500 and +protocols 50 and 51 to disallow it), I can build an IPsec tunnel from my +desktop to a machine in some remote office. Those packets will have one ESP +header throughout their life, for my end-to-end tunnel. For part of the +route, however, they will also have another ESP layer for the corporate VPN's +encapsulation. The whole header scheme for a packet on the Internet might +be:</p> +<ul> + <li>IP header (with gateway address) says next header --> ESP</li> + <li>ESP header <strong>[</strong> says next --> IP</li> + <li>IP header (with receiving machine address) says next header --> + ESP</li> + <li>ESP header <strong>[</strong> says next --> TCP</li> + <li>TCP header port number --> which process to send data to</li> + <li>data <strong>]]</strong></li> +</ul> + +<p>The first ESP (outermost) header is for the corporate VPN. The inner ESP +header is for the secure machine-to-machine link.</p> + +<h3><a name="dhr">DHR on the updown script</a></h3> + +<p>Here are some mailing list comments from <a +href="manpage.d/ipsec_pluto.8.html">pluto(8)</a> developer Hugh Redelmeier on +an earlier draft of this document:</p> +<pre>There are many important things left out + +- firewalling is important but must reflect (implement) policy. Since + policy isn't the same for all our customers, and we're not experts, + we should concentrate on FW and MASQ interactions with FreeS/WAN. + +- we need a diagram to show packet flow WITHIN ONE MACHINE, assuming + IKE, IPsec, FW, and MASQ are all done on that machine. The flow is + obvious if the components are run on different machines (trace the + cables). + + IKE input: + + packet appears on public IF, as UDP port 500 + + input firewalling rules are applied (may discard) + + Pluto sees the packet. + + IKE output: + + Pluto generates the packet & writes to public IF, UDP port 500 + + output firewalling rules are applied (may discard) + + packet sent out public IF + + IPsec input, with encapsulated packet, outer destination of this host: + + packet appears on public IF, protocol 50 or 51. If this + packet is the result of decapsulation, it will appear + instead on the paired ipsec IF. + + input firewalling rules are applied (but packet is opaque) + + KLIPS decapsulates it, writes result to paired ipsec IF + + input firewalling rules are applied to resulting packet + as input on ipsec IF + + if the destination of the packet is this machine, the + packet is passed on to the appropriate protocol handler. + If the original packet was encapsulated more than once + and the new outer destination is this machine, that + handler will be KLIPS. + + otherwise: + * routing is done for the resulting packet. This may well + direct it into KLIPS for encoding or encrypting. What + happens then is described elsewhere. + * forwarding firewalling rules are applied + * output firewalling rules are applied + * the packet is sent where routing specified + + IPsec input, with encapsulated packet, outer destination of another host: + + packet appears on some IF, protocol 50 or 51 + + input firewalling rules are applied (but packet is opaque) + + routing selects where to send the packet + + forwarding firewalling rules are applied (but packet is opaque) + + packet forwarded, still encapsulated + + IPsec output, from this host or from a client: + + if from a client, input firewalling rules are applied as the + packet arrives on the private IF + + routing directs the packet to an ipsec IF (this is how the + system decides KLIPS processing is required) + + if from a client, forwarding firewalling rules are applied + + KLIPS eroute mechanism matches the source and destination + to registered eroutes, yielding a SPI group. This dictates + processing, and where the resulting packet is to be sent + (the destinations SG and the nexthop). + + output firewalling is not applied to the resulting + encapsulated packet + +- Until quite recently, KLIPS would double encapsulate packets that + didn't strictly need to be. Firewalling should be prepared for + those packets showing up as ESP and AH protocol input packets on + an ipsec IF. + +- MASQ processing seems to be done as if it were part of the + forwarding firewall processing (this should be verified). + +- If a firewall is being used, it is likely the case that it needs to + be adjusted whenever IPsec SAs are added or removed. Pluto invokes + a script to do this (and to adjust routing) at suitable times. The + default script is only suitable for ipfwadm-managed firewalls. Under + LINUX 2.2.x kernels, ipchains can be managed by ipfwadm (emulation), + but ipchains more powerful if manipulated using the ipchains command. + In this case, a custom updown script must be used. + + We think that the flexibility of ipchains precludes us supplying an + updown script that would be widely appropriate.</pre> +</body> +</html> diff --git a/doc/src/forwardingstate.txt b/doc/src/forwardingstate.txt new file mode 100644 index 000000000..8853ac84e --- /dev/null +++ b/doc/src/forwardingstate.txt @@ -0,0 +1,35 @@ + + + .--------------. + | non-existant | + | policy | + `--------------' + | + | PF_ACQUIRE + | + |<---------. + V | new packet + .--------------. | (maybe resend PF_ACQUIRE) + | hold policy |--' + | |--. + `--------------' \ pass + | | \ msg .---------. + | | \ V | forward + | | .-------------. | packet + create | | | pass policy |--' + IPsec | | `-------------' + SA | | + | \ + | \ + V \ deny + .---------. \ msg + | encrypt | \ + | policy | \ ,---------. + `---------' \ | | discard + \ V | packet + .-------------. | + | deny policy |--' + '-------------' + + +$Id: forwardingstate.txt,v 1.1 2004/03/15 20:35:24 as Exp $ diff --git a/doc/src/glossary.html b/doc/src/glossary.html new file mode 100644 index 000000000..38d0db7bb --- /dev/null +++ b/doc/src/glossary.html @@ -0,0 +1,2257 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN glossary</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, glossary, cryptography"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: glossary.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="ourgloss">Glossary for the Linux FreeS/WAN project</a></h1> + +<p>Entries are in alphabetical order. Some entries are only one line or one +paragraph long. Others run to several paragraphs. I have tried to put the +essential information in the first paragraph so you can skip the other +paragraphs if that seems appropriate.</p> +<hr> + +<h2><a name="jump">Jump to a letter in the glossary</a></h2> + +<center> +<big><b><a href="#0">numeric</a> <a href="#A">A</a> <a href="#B">B</a> <a +href="#C">C</a> <a href="#D">D</a> <a href="#E">E</a> <a href="#F">F</a> <a +href="#G">G</a> <a href="#H">H</a> <a href="#I">I</a> <a href="#J">J</a> <a +href="#K">K</a> <a href="#L">L</a> <a href="#M">M</a> <a href="#N">N</a> <a +href="#O">O</a> <a href="#P">P</a> <a href="#Q">Q</a> <a href="#R">R</a> <a +href="#S">S</a> <a href="#T">T</a> <a href="#U">U</a> <a href="#V">V</a> <a +href="#W">W</a> <a href="#X">X</a> <a href="#Y">Y</a> <a +href="#Z">Z</a></b></big></center> +<hr> + +<h2><a name="gloss">Other glossaries</a></h2> + +<p>Other glossaries which overlap this one include:</p> +<ul> + <li>The VPN Consortium's glossary of <a + href="http://www.vpnc.org/terms.html">VPN terms</a>.</li> + <li>glossary portion of the <a + href="http://www.rsa.com/rsalabs/faq/B.html">Cryptography FAQ</a></li> + <li>an extensive crytographic glossary on <a + href="http://www.ciphersbyritter.com/GLOSSARY.HTM">Terry Ritter's</a> + page.</li> + <li>The <a href="#NSA">NSA</a>'s <a + href="http://www.sans.org/newlook/resources/glossary.htm">glossary of + computer security</a> on the <a href="http://www.sans.org">SANS + Institute</a> site.</li> + <li>a small glossary for Internet Security at <a + href="http://www5.zdnet.com/pcmag/pctech/content/special/glossaries/internetsecurity.html"> + PC magazine</a></li> + <li>The <a + href="http://www.visi.com/crypto/inet-crypto/glossary.html">glossary</a> + from Richard Smith's book <a href="#Smith">Internet Cryptography</a></li> +</ul> + +<p>Several Internet glossaries are available as RFCs:</p> +<ul> + <li><a href="http://www.rfc-editor.org/rfc/rfc1208.txt">Glossary of + Networking Terms</a></li> + <li><a href="http://www.rfc-editor.org/rfc/rfc1983.txt">Internet User's + Glossary</a></li> + <li><a href="http://www.rfc-editor.org/rfc/rfc2828.txt">Internet Security + Glossary</a></li> +</ul> + +<p>More general glossary or dictionary information:</p> +<ul> + <li>Free Online Dictionary of Computing (FOLDOC) + <ul> + <li><a href="http://www.nightflight.com/foldoc">North America</a></li> + <li><a + href="http://wombat.doc.ic.ac.uk/foldoc/index.html">Europe</a></li> + <li><a href="http://www.nue.org/foldoc/index.html">Japan</a></li> + </ul> + <p>There are many more mirrors of this dictionary.</p> + </li> + <li>The Jargon File, the definitive resource for hacker slang and folklore + <ul> + <li><a href="http://www.netmeg.net/jargon">North America</a></li> + <li><a href="http://info.wins.uva.nl/~mes/jargon/">Holland</a></li> + <li><a href="http://www.tuxedo.org/~esr/jargon">home page</a></li> + </ul> + <p>There are also many mirrors of this. See the home page for a list.</p> + </li> + <li>A general <a + href="http://www.trinity.edu/~rjensen/245glosf.htm#Navigate"> technology + glossary</a></li> + <li>An <a href="http://www.yourdictionary.com/">online dictionary resource + page</a> with pointers to many dictionaries for many languages</li> + <li>A <a href="http://www.onelook.com/">search engine</a> that accesses + several hundred online dictionaries</li> + <li>O'Reilly <a href="http://www.ora.com/reference/dictionary/">Dictionary + of PC Hardware and Data Communications Terms</a></li> + <li><a href="http://www.FreeSoft.org/CIE/index.htm">Connected</a> Internet + encyclopedia</li> + <li><a href="http://www.whatis.com/">whatis.com</a></li> +</ul> +<hr> + +<h2><a name="definitions">Definitions</a></h2> +<dl> + <dt><a name="0">0</a></dt> + <dt><a name="3DES">3DES (Triple DES)</a></dt> + <dd>Using three <a href="#DES">DES</a> encryptions on a single data + block, with at least two different keys, to get higher security than is + available from a single DES pass. The three-key version of 3DES is the + default encryption algorithm for <a href="#FreeSWAN">Linux + FreeS/WAN</a>. + <p><a href="#IPSEC">IPsec</a> always does 3DES with three different + keys, as required by RFC 2451. For an explanation of the two-key + variant, see <a href="#2key">two key triple DES</a>. Both use an <a + href="#EDE">EDE</a> encrypt-decrypt-encrpyt sequence of operations.</p> + <p>Single <a href="#DES">DES</a> is <a + href="politics.html#desnotsecure">insecure</a>.</p> + <p>Double DES is ineffective. Using two 56-bit keys, one might expect + an attacker to have to do 2<sup>112</sup> work to break it. In fact, + only 2<sup>57</sup> work is required with a <a + href="#meet">meet-in-the-middle attack</a>, though a large amount of + memory is also required. Triple DES is vulnerable to a similar attack, + but that just reduces the work factor from the 2<sup>168</sup> one + might expect to 2<sup>112</sup>. That provides adequate protection + against <a href="#brute">brute force</a> attacks, and no better attack + is known.</p> + <p>3DES can be somewhat slow compared to other ciphers. It requires + three DES encryptions per block. DES was designed for hardware + implementation and includes some operations which are difficult in + software. However, the speed we get is quite acceptable for many uses. + See our <a href="performance.html">performance</a> document for + details.</p> + </dd> + <dt><a name="A">A</a></dt> + <dt><a name="active">Active attack</a></dt> + <dd>An attack in which the attacker does not merely eavesdrop (see <a + href="#passive">passive attack</a>) but takes action to change, delete, + reroute, add, forge or divert data. Perhaps the best-known active + attack is <a href="#middle">man-in-the-middle</a>. In general, <a + href="#authentication">authentication</a> is a useful defense against + active attacks.</dd> + <dt><a name="AES">AES</a></dt> + <dd>The <b>A</b>dvanced <b>E</b>ncryption <b>S</b>tandard -- a new <a + href="#block">block cipher</a> standard to replace <a + href="politics.html#desnotsecure">DES</a> -- developed by <a + href="#NIST">NIST</a>, the US National Institute of Standards and + Technology. DES used 64-bit blocks and a 56-bit key. AES ciphers use a + 128-bit block and 128, 192 or 256-bit keys. The larger block size helps + resist <a href="#birthday">birthday attacks</a> while the large key + size prevents <a href="#brute">brute force attacks</a>. + <p>Fifteen proposals meeting NIST's basic criteria were submitted in + 1998 and subjected to intense discussion and analysis, "round one" + evaluation. In August 1999, NIST narrowed the field to five "round two" + candidates:</p> + <ul> + <li><a href="http://www.research.ibm.com/security/mars.html">Mars</a> + from IBM</li> + <li><a href="http://www.rsa.com/rsalabs/aes/">RC6</a> from RSA</li> + <li><a + href="http://www.esat.kuleuven.ac.be/~rijmen/rijndael/">Rijndael</a> + from two Belgian researchers</li> + <li><a + href="http://www.cl.cam.ac.uk/~rja14/serpent.html">Serpent</a>, a + British-Norwegian-Israeli collaboration</li> + <li><a href="http://www.counterpane.com/twofish.html">Twofish</a> + from the consulting firm <a + href="http://www.counterpane.com">Counterpane</a></li> + </ul> + <p>Three of the five finalists -- Rijndael, Serpent and Twofish -- have + completely open licenses.</p> + <p>In October 2000, NIST announced the winner -- Rijndael.</p> + <p>For more information, see:</p> + <ul> + <li>NIST's <a + href="http://csrc.nist.gov/encryption/aes/aes_home.htm">AES home + page</a></li> + <li>the Block Cipher Lounge <a + href="http://www.ii.uib.no/~larsr/aes.html">AES page</a></li> + <li>Brian Gladman's <a + href="http://fp.gladman.plus.com/cryptography_technology/index.htm">code + and benchmarks</a></li> + <li>Helger Lipmaa's <a + href="http://www.tcs.hut.fi/~helger/aes/">survey of + implementations</a></li> + </ul> + <p>AES will be added to a future release of <a href="#FreeSWAN">Linux + FreeS/WAN</a>. Likely we will add all three of the finalists with good + licenses. User-written <a href="web.html#patch">AES patches</a> are + already available.</p> + <p>Adding AES may also require adding stronger hashes, <a + href="#SHA-256">SHA-256, SHA-384 and SHA-512</a>.</p> + </dd> + <dt><a name="AH">AH</a></dt> + <dd>The <a href="#IPSEC">IPsec</a> <b>A</b>uthentication <b>H</b>eader, + added after the IP header. For details, see our <a + href="ipsec.html#AH.ipsec">IPsec</a> document and/or RFC 2402.</dd> + <dt><a name="alicebob">Alice and Bob</a></dt> + <dd>A and B, the standard example users in writing on cryptography and + coding theory. Carol and Dave join them for protocols which require + more players. + <p>Bruce Schneier extends these with many others such as Eve the + Eavesdropper and Victor the Verifier. His extensions seem to be in the + process of becoming standard as well. See page 23 of <a + href="biblio.html#schneier">Applied Cryptography</a></p> + <p>Alice and Bob have an amusing <a + href="http://www.conceptlabs.co.uk/alicebob.html"> biography</a> on the + web.</p> + </dd> + <dt>ARPA</dt> + <dd>see <a href="#DARPA">DARPA</a></dd> + <dt><a name="ASIO">ASIO</a></dt> + <dd>Australian Security Intelligence Organisation.</dd> + <dt>Asymmetric cryptography</dt> + <dd>See <a href="#public">public key cryptography</a>.</dd> + <dt><a name="authentication">Authentication</a></dt> + <dd>Ensuring that a message originated from the expected sender and has + not been altered on route. <a href="#IPSEC">IPsec</a> uses + authentication in two places: + <ul> + <li>peer authentication, authenticating the players in <a + href="#IKE">IKE</a>'s <a href="#DH">Diffie-Hellman</a> key + exchanges to prevent <a href="#middle">man-in-the-middle + attacks</a>. This can be done in a number of ways. The methods + supported by FreeS/WAN are discussed in our <a + href="adv_config.html#choose">advanced configuration</a> + document.</li> + <li>packet authentication, authenticating packets on an established + <a href="#SA">SA</a>, either with a separate <a + href="#AH">authentication header</a> or with the optional + authentication in the <a href="#ESP">ESP</a> protocol. In either + case, packet authentication uses a <a href="#HMAC">hashed message + athentication code</a> technique.</li> + </ul> + <p>Outside IPsec, passwords are perhaps the most common authentication + mechanism. Their function is essentially to authenticate the person's + identity to the system. Passwords are generally only as secure as the + network they travel over. If you send a cleartext password over a + tapped phone line or over a network with a packet sniffer on it, the + security provided by that password becomes zero. Sending an encrypted + password is no better; the attacker merely records it and reuses it at + his convenience. This is called a <a href="#replay">replay</a> + attack.</p> + <p>A common solution to this problem is a <a + href="#challenge">challenge-response</a> system. This defeats simple + eavesdropping and replay attacks. Of course an attacker might still try + to break the cryptographic algorithm used, or the <a + href="#random">random number</a> generator.</p> + </dd> + <dt><a name="auto">Automatic keying</a></dt> + <dd>A mode in which keys are automatically generated at connection + establisment and new keys automaically created periodically thereafter. + Contrast with <a href="#manual">manual keying</a> in which a single + stored key is used. + <p>IPsec uses the <a href="#DH">Diffie-Hellman key exchange + protocol</a> to create keys. An <a + href="#authentication">authentication</a> mechansim is required for + this. FreeS/WAN normally uses <a href="#RSA">RSA</a> for this. Other + methods supported are discussed in our <a + href="adv_config.html#choose">advanced configuration</a> document.</p> + <p>Having an attacker break the authentication is emphatically not a + good idea. An attacker that breaks authentication, and manages to + subvert some other network entities (DNS, routers or gateways), can use + a <a href="#middle">man-in-the middle attack</a> to break the security + of your IPsec connections.</p> + <p>However, having an attacker break the authentication in automatic + keying is not quite as bad as losing the key in manual keying.</p> + <ul> + <li>An attacker who reads /etc/ipsec.conf and gets the keys for a + manually keyed connection can, without further effort, read all + messages encrypted with those keys, including any old messages he + may have archived.</li> + <li>Automatic keying has a property called <a href="#PFS">perfect + forward secrecy</a>. An attacker who breaks the authentication gets + none of the automatically generated keys and cannot immediately + read any messages. He has to mount a successful <a + href="#middle">man-in-the-middle attack</a> in real time before he + can read anything. He cannot read old archived messages at all and + will not be able to read any future messages not caught by + man-in-the-middle tricks.</li> + </ul> + <p>That said, the secrets used for authentication, stored in <a + href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a>, should + still be protected as tightly as cryptographic keys.</p> + </dd> + <dt><a name="B">B</a></dt> + <dt><a href="http://www.nortelnetworks.com">Bay Networks</a></dt> + <dd>A vendor of routers, hubs and related products, now a subsidiary of + Nortel. Interoperation between their IPsec products and Linux FreeS/WAN + was problematic at last report; see our <a + href="interop.html#bay">interoperation</a> section.</dd> + <dt><a name="benchmarks">benchmarks</a></dt> + <dd>Our default block cipher, <a href="#3DES">triple DES</a>, is slower + than many alternate ciphers that might be used. Speeds achieved, + however, seem adequate for many purposes. For example, the assembler + code from the <a href="#LIBDES">LIBDES</a> library we use encrypts 1.6 + megabytes per second on a Pentium 200, according to the test program + supplied with the library. + <p>For more detail, see our document on <a + href="performance.html">FreeS/WAN performance</a>.</p> + </dd> + <dt><a name="BIND">BIND</a></dt> + <dd><b>B</b>erkeley <b>I</b>nternet <b>N</b>ame <b>D</b>aemon, a widely + used implementation of <a href="#DNS">DNS</a> (Domain Name Service). + See our bibliography for a <a href="#DNS">useful reference</a>. See the + <a href="http://www.isc.org/bind.html">BIND home page</a> for more + information and the latest version.</dd> + <dt><a name="birthday">Birthday attack</a></dt> + <dd>A cryptographic attack based on the mathematics exemplified by the <a + href="#paradox">birthday paradox</a>. This math turns up whenever the + question of two cryptographic operations producing the same result + becomes an issue: + <ul> + <li><a href="#collision">collisions</a> in <a href="#digest">message + digest</a> functions.</li> + <li>identical output blocks from a <a href="#block">block + cipher</a></li> + <li>repetition of a challenge in a <a + href="#challenge">challenge-response</a> system</li> + </ul> + <p>Resisting such attacks is part of the motivation for:</p> + <ul> + <li>hash algorithms such as <a href="#SHA">SHA</a> and <a + href="#RIPEMD">RIPEMD-160</a> giving a 160-bit result rather than + the 128 bits of <a href="#MD4">MD4</a>, <a href="#MD5">MD5</a> and + <a href="#RIPEMD">RIPEMD-128</a>.</li> + <li><a href="#AES">AES</a> block ciphers using a 128-bit block + instead of the 64-bit block of most current ciphers</li> + <li><a href="#IPSEC">IPsec</a> using a 32-bit counter for packets + sent on an <a href="#auto">automatically keyed</a> <a + href="#SA">SA</a> and requiring that the connection always be + rekeyed before the counter overflows.</li> + </ul> + </dd> + <dt><a name="paradox">Birthday paradox</a></dt> + <dd>Not really a paradox, just a rather counter-intuitive mathematical + fact. In a group of 23 people, the chance of a least one pair having + the same birthday is over 50%. + <p>The second person has 1 chance in 365 (ignoring leap years) of + matching the first. If they don't match, the third person's chances of + matching one of them are 2/365. The 4th, 3/365, and so on. The total of + these chances grows more quickly than one might guess.</p> + </dd> + <dt><a name="block">Block cipher</a></dt> + <dd>A <a href="#symmetric">symmetric cipher</a> which operates on + fixed-size blocks of plaintext, giving a block of ciphertext for each. + Contrast with <a href="#stream"> stream cipher</a>. Block ciphers can + be used in various <a href="#mode">modes</a> when multiple block are to + be encrypted. + <p><a href="#DES">DES</a> is among the the best known and widely used + block ciphers, but is now obsolete. Its 56-bit key size makes it <a + href="#desnotsecure">highly insecure</a> today. <a href="#3DES">Triple + DES</a> is the default block cipher for <a href="#FreeSWAN">Linux + FreeS/WAN</a>.</p> + <p>The current generation of block ciphers -- such as <a + href="#Blowfish">Blowfish</a>, <a href="#CAST128">CAST-128</a> and <a + href="#IDEA">IDEA</a> -- all use 64-bit blocks and 128-bit keys. The + next generation, <a href="#AES">AES</a>, uses 128-bit blocks and + supports key sizes up to 256 bits.</p> + <p>The <a href="http://www.ii.uib.no/~larsr/bc.html"> Block Cipher + Lounge</a> web site has more information.</p> + </dd> + <dt><a name="Blowfish">Blowfish</a></dt> + <dd>A <a href="#block">block cipher</a> using 64-bit blocks and keys of + up to 448 bits, designed by <a href="#schneier">Bruce Schneier</a> and + used in several products. + <p>This is not required by the <a href="#IPSEC">IPsec</a> RFCs and not + currently used in <a href="#FreeSWAN">Linux FreeS/WAN</a>.</p> + </dd> + <dt><a name="brute">Brute force attack (exhaustive search)</a></dt> + <dd>Breaking a cipher by trying all possible keys. This is always + possible in theory (except against a <a href="#OTP">one-time pad</a>), + but it becomes practical only if the key size is inadequate. For an + important example, see our document on the <a + href="#desnotsecure">insecurity of DES</a> with its 56-bit key. For an + analysis of key sizes required to resist plausible brute force attacks, + see <a href="http://www.counterpane.com/keylength.html">this paper</a>. + <p>Longer keys protect against brute force attacks. Each extra bit in + the key doubles the number of possible keys and therefore doubles the + work a brute force attack must do. A large enough key defeats + <strong>any</strong> brute force attack.</p> + <p>For example, the EFF's <a href="#EFF">DES Cracker</a> searches a + 56-bit key space in an average of a few days. Let us assume an attacker + that can find a 64-bit key (256 times harder) by brute force search in + a second (a few hundred thousand times faster). For a 96-bit key, that + attacker needs 2<sup>32</sup> seconds, about 135 years. Against a + 128-bit key, he needs 2<sup>32</sup> times that, over 500,000,000,000 + years. Your data is then obviously secure against brute force attacks. + Even if our estimate of the attacker's speed is off by a factor of a + million, it still takes him over 500,000 years to crack a message.</p> + <p>This is why</p> + <ul> + <li>single <a href="#DES">DES</a> is now considered <a + href="#desnotsecure">dangerously insecure</a></li> + <li>all of the current generation of <a href="#block">block + ciphers</a> use a 128-bit or longer key</li> + <li><a href="#AES">AES</a> ciphers support keysizes 128, 192 and 256 + bits</li> + <li>any cipher we add to Linux FreeS/WAN will have <em>at least</em> + a 128-bit key</li> + </ul> + <p><strong>Cautions:</strong><br> + <em>Inadequate keylength always indicates a weak cipher</em> but it is + important to note that <em>adequate keylength does not necessarily + indicate a strong cipher</em>. There are many attacks other than brute + force, and adequate keylength <em>only</em> guarantees resistance to + brute force. Any cipher, whatever its key size, will be weak if design + or implementation flaws allow other attacks.</p> + <p>Also, <em>once you have adequate keylength</em> (somewhere around 90 + or 100 bits), <em>adding more key bits make no practical + difference</em>, even against brute force. Consider our 128-bit example + above that takes 500,000,000,000 years to break by brute force. We + really don't care how many zeroes there are on the end of that, as long + as the number remains ridiculously large. That is, we don't care + exactly how large the key is as long as it is large enough.</p> + <p>There may be reasons of convenience in the design of the cipher to + support larger keys. For example <a href="#Blowfish">Blowfish</a> + allows up to 448 bits and <a href="#RC4">RC4</a> up to 2048, but beyond + 100-odd bits it makes no difference to practical security.</p> + </dd> + <dt>Bureau of Export Administration</dt> + <dd>see <a href="#BXA">BXA</a></dd> + <dt><a name="BXA">BXA</a></dt> + <dd>The US Commerce Department's <b>B</b>ureau of E<b>x</b>port + <b>A</b>dministration which administers the <a href="#EAR">EAR</a> + Export Administration Regulations controling the export of, among other + things, cryptography.</dd> + <dt><a name="C">C</a></dt> + <dt><a name="CA">CA</a></dt> + <dd><b>C</b>ertification <b>A</b>uthority, an entity in a <a + href="#PKI">public key infrastructure</a> that can certify keys by + signing them. Usually CAs form a hierarchy. The top of this hierarchy + is called the <a href="#rootCA">root CA</a>. + <p>See <a href="#web">Web of Trust</a> for an alternate model.</p> + </dd> + <dt><a name="CAST128">CAST-128</a></dt> + <dd>A <a href="#block">block cipher</a> using 64-bit blocks and 128-bit + keys, described in RFC 2144 and used in products such as <a + href="#Entrust">Entrust</a> and recent versions of <a + href="#PGP">PGP</a>. + <p>This is not required by the <a href="#IPSEC">IPsec</a> RFCs and not + currently used in <a href="#FreeSWAN">Linux FreeS/WAN</a>.</p> + </dd> + <dt>CAST-256</dt> + <dd><a href="#Entrust">Entrust</a>'s candidate cipher for the <a + href="#AES">AES standard</a>, largely based on the <a + href="#CAST128">CAST-128</a> design.</dd> + <dt><a name="CBC">CBC mode</a></dt> + <dd><b>C</b>ipher <b>B</b>lock <b>C</b>haining <a href="#mode">mode</a>, + a method of using a <a href="#block">block cipher</a> in which for each + block except the first, the result of the previous encryption is XORed + into the new block before it is encrypted. CBC is the mode used in <a + href="#IPSEC">IPsec</a>. + <p>An <a href="#IV">initialisation vector</a> (IV) must be provided. It + is XORed into the first block before encryption. The IV need not be + secret but should be different for each message and unpredictable.</p> + </dd> + <dt><a name="CIDR">CIDR</a></dt> + <dd><b>C</b>lassless <b>I</b>nter-<b>D</b>omain <b>R</b>outing, + an addressing scheme used to describe networks not + restricted to the old Class A, B, and C sizes. + A CIDR block is written + <VAR>address</VAR>/<VAR>mask</VAR>, where <VAR>address</VAR> is + a 32-bit Internet address. + The first <VAR>mask</VAR> bits of <VAR>address</VAR> + are part of the gateway address, while the remaining bits designate + other host addresses. + For example, the CIDR block 192.0.2.96/27 describes a network with + gateway + 192.0.2.96, hosts 192.0.2.96 through 192.0.2.126 and broadcast + 192.0.2.127. + <p>FreeS/WAN policy group files accept CIDR blocks of the format + <VAR>address</VAR>/[<VAR>mask</VAR>], where <VAR>address</VAR> may + take the form <VAR>name.domain.tld</VAR>. An absent <VAR>mask</VAR> + is assumed to be /32. + </p> + </dd> + + <dt>Certification Authority</dt> + <dd>see <a href="#CA">CA</a></dd> + <dt><a name="challenge">Challenge-response authentication</a></dt> + <dd>An <a href="#authentication">authentication</a> system in which one + player generates a <a href="#random">random number</a>, encrypts it and + sends the result as a challenge. The other player decrypts and sends + back the result. If the result is correct, that proves to the first + player that the second player knew the appropriate secret, required for + the decryption. Variations on this technique exist using <a + href="#public">public key</a> or <a href="#symmetric">symmetric</a> + cryptography. Some provide two-way authentication, assuring each player + of the other's identity. + <p>This is more secure than passwords against two simple attacks:</p> + <ul> + <li>If cleartext passwords are sent across the wire (e.g. for + telnet), an eavesdropper can grab them. The attacker may even be + able to break into other systems if the user has chosen the same + password for them.</li> + <li>If an encrypted password is sent, an attacker can record the + encrypted form and use it later. This is called a replay + attack.</li> + </ul> + <p>A challenge-response system never sends a password, either cleartext + or encrypted. An attacker cannot record the response to one challenge + and use it as a response to a later challenge. The random number is + different each time.</p> + <p>Of course an attacker might still try to break the cryptographic + algorithm used, or the <a href="#random">random number</a> + generator.</p> + </dd> + <dt><a name="mode">Cipher Modes</a></dt> + <dd>Different ways of using a block cipher when encrypting multiple + blocks. + <p>Four standard modes were defined for <a href="#DES">DES</a> in <a + href="#FIPS">FIPS</a> 81. They can actually be applied with any block + cipher.</p> + + <table> + <tbody> + <tr> + <td></td> + <td><a href="#ECB">ECB</a></td> + <td>Electronic CodeBook</td> + <td>encrypt each block independently</td> + </tr> + <tr> + <td></td> + <td><a href="#CBC">CBC</a></td> + <td>Cipher Block Chaining<br> + </td> + <td>XOR previous block ciphertext into new block plaintext before + encrypting new block</td> + </tr> + <tr> + <td></td> + <td>CFB</td> + <td>Cipher FeedBack</td> + <td></td> + </tr> + <tr> + <td></td> + <td>OFB</td> + <td>Output FeedBack</td> + <td></td> + </tr> + </tbody> + </table> + <p><a href="#IPSEC">IPsec</a> uses <a href="#CBC">CBC</a> mode since + this is only marginally slower than <a href="#ECB">ECB</a> and is more + secure. In ECB mode the same plaintext always encrypts to the same + ciphertext, unless the key is changed. In CBC mode, this does not + occur.</p> + <p>Various other modes are also possible, but none of them are used in + IPsec.</p> + </dd> + <dt><a name="ciphertext">Ciphertext</a></dt> + <dd>The encrypted output of a cipher, as opposed to the unencrypted <a + href="#plaintext">plaintext</a> input.</dd> + <dt><a href="http://www.cisco.com">Cisco</a></dt> + <dd>A vendor of routers, hubs and related products. Their IPsec products + interoperate with Linux FreeS/WAN; see our <a + href="interop.html#Cisco">interop</a> section.</dd> + <dt><a name="client">Client</a></dt> + <dd>This term has at least two distinct uses in discussing IPsec: + <ul> + <li>The <strong>clients of an IPsec gateway</strong> are the machines + it protects, typically on one or more subnets behind the gateway. + In this usage, all the machines on an office network are clients of + that office's IPsec gateway. Laptop or home machines connecting to + the office, however, are <em>not</em> clients of that gateway. They + are remote gateways, running the other end of an IPsec connection. + Each of them is also its own client.</li> + <li><strong>IPsec client software</strong> is used to describe + software which runs on various standalone machines to let them + connect to IPsec networks. In this usage, a laptop or home machine + connecting to the office is a client, and the office gateway is the + server.</li> + </ul> + <p>We generally use the term in the first sense. Vendors of Windows + IPsec solutions often use it in the second. See this <a + href="interop.html#client.server">discussion</a>.</p> + </dd> + <dt><a name="cc">Common Criteria</a></dt> + <dd>A set of international security classifications which are replacing + the old US <a href="#rainbow">Rainbow Book</a> standards and similar + standards in other countries. + <p>Web references include this <a href="http://csrc.nist.gov/cc">US + government site</a> and this <a + href="http://www.commoncriteria.org">global home page</a>.</p> + </dd> + <dt>Conventional cryptography</dt> + <dd>See <a href="#symmetric">symmetric cryptography</a></dd> + <dt><a name="collision">Collision resistance</a></dt> + <dd>The property of a <a href="#digest">message digest</a> algorithm + which makes it hard for an attacker to find or construct two inputs + which hash to the same output.</dd> + <dt>Copyleft</dt> + <dd>see GNU <a href="#GPL">General Public License</a></dd> + <dt><a name="CSE">CSE</a></dt> + <dd><a href="http://www.cse-cst.gc.ca/">Communications Security + Establishment</a>, the Canadian organisation for <a + href="#SIGINT">signals intelligence</a>.</dd> + <dt><a name="D">D</a></dt> + <dt><a name="DARPA">DARPA (sometimes just ARPA)</a></dt> + <dd>The US government's <b>D</b>efense <b>A</b>dvanced <b>R</b>esearch + <b>P</b>rojects <b>A</b>gency. Projects they have funded over the years + have included the Arpanet which evolved into the Internet, the TCP/IP + protocol suite (as a replacement for the original Arpanet suite), the + Berkeley 4.x BSD Unix projects, and <a href="#SDNS">Secure DNS</a>. + <p>For current information, see their <a + href="http://www.darpa.mil/ito">web site</a>.</p> + </dd> + <dt><a name="DOS">Denial of service (DoS) attack</a></dt> + <dd>An attack that aims at denying some service to legitimate users of a + system, rather than providing a service to the attacker. + <ul> + <li>One variant is a flooding attack, overwhelming the system with + too many packets, to much email, or whatever.</li> + <li>A closely related variant is a resource exhaustion attack. For + example, consider a "TCP SYN flood" attack. Setting up a TCP + connection involves a three-packet exchange: + <ul> + <li>Initiator: Connection please (SYN)</li> + <li>Responder: OK (ACK)</li> + <li>Initiator: OK here too</li> + </ul> + <p>If the attacker puts bogus source information in the first + packet, such that the second is never delivered, the responder may + wait a long time for the third to come back. If responder has + already allocated memory for the connection data structures, and if + many of these bogus packets arrive, the responder may run out of + memory.</p> + </li> + <li>Another variant is to feed the system undigestible data, hoping + to make it sick. For example, IP packets are limited in size to 64K + bytes and a fragment carries information on where it starts within + that 64K and how long it is. The "ping of death" delivers fragments + that say, for example, that they start at 60K and are 20K long. + Attempting to re-assemble these without checking for overflow can + be fatal.</li> + </ul> + <p>The two example attacks discussed were both quite effective when + first discovered, capable of crashing or disabling many operating + systems. They were also well-publicised, and today far fewer systems + are vulnerable to them.</p> + </dd> + <dt><a name="DES">DES</a></dt> + <dd>The <b>D</b>ata <b>E</b>ncryption <b>S</b>tandard, a <a + href="#block">block cipher</a> with 64-bit blocks and a 56-bit key. + Probably the most widely used <a href="#symmetric">symmetric cipher</a> + ever devised. DES has been a US government standard for their own use + (only for unclassified data), and for some regulated industries such as + banking, since the late 70's. It is now being replaced by <a + href="#AES">AES</a>. + <p><a href="politics.html#desnotsecure">DES is seriously insecure + against current attacks.</a></p> + <p><a href="#FreeSWAN">Linux FreeS/WAN</a> does not include DES, even + though the RFCs specify it. <b>We strongly recommend that single DES + not be used.</b></p> + <p>See also <a href="#3DES">3DES</a> and <a href="#DESX">DESX</a>, + stronger ciphers based on DES.</p> + </dd> + <dt><a name="DESX">DESX</a></dt> + <dd>An improved <a href="#DES">DES</a> suggested by Ron Rivest of RSA + Data Security. It XORs extra key material into the text before and + after applying the DES cipher. + <p>This is not required by the <a href="#IPSEC">IPsec</a> RFCs and not + currently used in <a href="#FreeSWAN">Linux FreeS/WAN</a>. DESX would + be the easiest additional transform to add; there would be very little + code to write. It would be much faster than 3DES and almost certainly + more secure than DES. However, since it is not in the RFCs other IPsec + implementations cannot be expected to have it.</p> + </dd> + <dt>DH</dt> + <dd>see <a href="#DH">Diffie-Hellman</a></dd> + <dt><a name="DHCP">DHCP</a></dt> + <dd><strong>D</strong>ynamic <strong>H</strong>ost + <strong>C</strong>onfiguration <strong>P</strong>rotocol, a method of + assigning <a href="#dynamic">dynamic IP addresses</a>, and providing + additional information such as addresses of DNS servers and of + gateways. See this <a href="http://www.dhcp.org">DHCP resource + page.</a></dd> + <dt><a name="DH">Diffie-Hellman (DH) key exchange protocol</a></dt> + <dd>A protocol that allows two parties without any initial shared secret + to create one in a manner immune to eavesdropping. Once they have done + this, they can communicate privately by using that shared secret as a + key for a block cipher or as the basis for key exchange. + <p>The protocol is secure against all <a href="#passive">passive + attacks</a>, but it is not at all resistant to active <a + href="#middle">man-in-the-middle attacks</a>. If a third party can + impersonate Bob to Alice and vice versa, then no useful secret can be + created. Authentication of the participants is a prerequisite for safe + Diffie-Hellman key exchange. IPsec can use any of several <a + href="#authentication">authentication</a> mechanisims. Those supported + by FreeS/WAN are discussed in our <a + href="config.html#choose">configuration</a> section.</p> + <p>The Diffie-Hellman key exchange is based on the <a + href="#dlog">discrete logarithm</a> problem and is secure unless + someone finds an efficient solution to that problem.</p> + <p>Given a prime <var>p</var> and generator <var>g</var> (explained + under <a href="#dlog">discrete log</a> below), Alice:</p> + <ul> + <li>generates a random number <var>a</var></li> + <li>calculates <var>A = g^a modulo p</var></li> + <li>sends <var>A</var> to Bob</li> + </ul> + <p>Meanwhile Bob:</p> + <ul> + <li>generates a random number <var>b</var></li> + <li>calculates <var>B = g^b modulo p</var></li> + <li>sends <var>B</var> to Alice</li> + </ul> + <p>Now Alice and Bob can both calculate the shared secret <var>s = + g^(ab)</var>. Alice knows <var>a</var> and <var>B</var>, so she + calculates <var>s = B^a</var>. Bob knows <var>A</var> and <var>b</var> + so he calculates <var>s = A^b</var>.</p> + <p>An eavesdropper will know <var>p</var> and <var>g</var> since these + are made public, and can intercept <var>A</var> and <var>B</var> but, + short of solving the <a href="#dlog">discrete log</a> problem, these do + not let him or her discover the secret <var>s</var>.</p> + </dd> + <dt><a name="signature">Digital signature</a></dt> + <dd>Sender: + <ul> + <li>calculates a <a href="#digest">message digest</a> of a + document</li> + <li>encrypts the digest with his or her private key, using some <a + href="#public">public key cryptosystem</a>.</li> + <li>attaches the encrypted digest to the document as a signature</li> + </ul> + <p>Receiver:</p> + <ul> + <li>calculates a digest of the document (not including the + signature)</li> + <li>decrypts the signature with the signer's public key</li> + <li>verifies that the two results are identical</li> + </ul> + <p>If the public-key system is secure and the verification succeeds, + then the receiver knows</p> + <ul> + <li>that the document was not altered between signing and + verification</li> + <li>that the signer had access to the private key</li> + </ul> + <p>Such an encrypted message digest can be treated as a signature since + it cannot be created without <em>both</em> the document <em>and</em> + the private key which only the sender should possess. The <a + href="web.html#legal">legal issues</a> are complex, but several + countries are moving in the direction of legal recognition for digital + signatures.</p> + </dd> + <dt><a name="dlog">discrete logarithm problem</a></dt> + <dd>The problem of finding logarithms in a finite field. Given a field + defintion (such definitions always include some operation analogous to + multiplication) and two numbers, a base and a target, find the power + which the base must be raised to in order to yield the target. + <p>The discrete log problem is the basis of several cryptographic + systems, including the <a href="#DH">Diffie-Hellman</a> key exchange + used in the <a href="#IKE">IKE</a> protocol. The useful property is + that exponentiation is relatively easy but the inverse operation, + finding the logarithm, is hard. The cryptosystems are designed so that + the user does only easy operations (exponentiation in the field) but an + attacker must solve the hard problem (discrete log) to crack the + system.</p> + <p>There are several variants of the problem for different types of + field. The IKE/Oakley key determination protocol uses two variants, + either over a field modulo a prime or over a field defined by an + elliptic curve. We give an example modulo a prime below. For the + elliptic curve version, consult an advanced text such as <a + href="biblio.html#handbook">Handbook of Applied Cryptography</a>.</p> + <p>Given a prime <var>p</var>, a generator <var>g</var> for the field + modulo that prime, and a number <var>x</var> in the field, the problem + is to find <var>y</var> such that <var>g^y = x</var>.</p> + <p>For example, let p = 13. The field is then the integers from 0 to + 12. Any integer equals one of these modulo 13. That is, the remainder + when any integer is divided by 13 must be one of these.</p> + <p>2 is a generator for this field. That is, the powers of two modulo + 13 run through all the non-zero numbers in the field. Modulo 13 we + have:</p> + <pre> y x + 2^0 == 1 + 2^1 == 2 + 2^2 == 4 + 2^3 == 8 + 2^4 == 3 that is, the remainder from 16/13 is 3 + 2^5 == 6 the remainder from 32/13 is 6 + 2^6 == 12 and so on + 2^7 == 11 + 2^8 == 9 + 2^9 == 5 + 2^10 == 10 + 2^11 == 7 + 2^12 == 1</pre> + <p>Exponentiation in such a field is not difficult. Given, say, + <nobr><var>y = 11</var>,</nobr>calculating <nobr><var>x = + 7</var></nobr>is straightforward. One method is just to calculate + <nobr><var>2^11 = 2048</var>,</nobr>then <nobr><var>2048 mod 13 == + 7</var>.</nobr>When the field is modulo a large prime (say a few 100 + digits) you need a silghtly cleverer method and even that is moderately + expensive in computer time, but the calculation is still not + problematic in any basic way.</p> + <p>The discrete log problem is the reverse. In our example, given + <nobr><var>x = 7</var>,</nobr>find the logarithm <nobr><var>y = + 11</var>.</nobr>When the field is modulo a large prime (or is based on + a suitable elliptic curve), this is indeed problematic. No solution + method that is not catastrophically expensive is known. Quite a few + mathematicians have tackled this problem. No efficient method has been + found and mathematicians do not expect that one will be. It seems + likely no efficient solution to either of the main variants the + discrete log problem exists.</p> + <p>Note, however, that no-one has proven such methods do not exist. If + a solution to either variant were found, the security of any crypto + system using that variant would be destroyed. This is one reason <a + href="#IKE">IKE</a> supports two variants. If one is broken, we can + switch to the other.</p> + </dd> + <dt><a name="discretionary">discretionary access control</a></dt> + <dd>access control mechanisms controlled by the user, for example Unix + rwx file permissions. These contrast with <a + href="#mandatory">mandatory access controls</a>.</dd> + <dt><a name="DNS">DNS</a></dt> + <dd><b>D</b>omain <b>N</b>ame <b>S</b>ervice, a distributed database + through which names are associated with numeric addresses and other + information in the Internet Protocol Suite. See also the <a + href="background.html#dns.background">DNS background</a> section of our + documentation.</dd> + <dt>DOS attack</dt> + <dd>see <a href="#DOS">Denial Of Service</a> attack</dd> + <dt><a name="dynamic">dynamic IP address</a></dt> + <dd>an IP address which is automatically assigned, either by <a + href="#DHCP">DHCP</a> or by some protocol such as <a + href="#PPP">PPP</a> or <a href="#PPPoE">PPPoE</a> which the machine + uses to connect to the Internet. This is the opposite of a <a + href="#static">static IP address</a>, pre-set on the machine + itself.</dd> + <dt><a name="E">E</a></dt> + <dt><a name="EAR">EAR</a></dt> + <dd>The US government's <b>E</b>xport <b>A</b>dministration + <b>R</b>egulations, administered by the <a href="#BXA">Bureau of Export + Administration</a>. These have replaced the earlier <a + href="#ITAR">ITAR</a> regulations as the controls on export of + cryptography.</dd> + <dt><a name="ECB">ECB mode</a></dt> + <dd><b>E</b>lectronic <b>C</b>ode<b>B</b>ook mode, the simplest way to + use a block cipher. See <a href="#mode">Cipher Modes</a>.</dd> + <dt><a name="EDE">EDE</a></dt> + <dd>The sequence of operations normally used in either the three-key + variant of <a href="#3DES">triple DES</a> used in <a + href="#IPSEC">IPsec</a> or the <a href="#2key">two-key</a> variant used + in some other systems. + <p>The sequence is:</p> + <ul> + <li><b>E</b>ncrypt with key1</li> + <li><b>D</b>ecrypt with key2</li> + <li><b>E</b>ncrypt with key3</li> + </ul> + <p>For the two-key version, key1=key3.</p> + <p>The "advantage" of this EDE order of operations is that it makes it + simple to interoperate with older devices offering only single DES. Set + key1=key2=key3 and you have the worst of both worlds, the overhead of + triple DES with the "security" of single DES. Since both the <a + href="politics.html#desnotsecure">security of single DES</a> and the + overheads of triple DES are seriously inferior to many other ciphers, + this is a spectacularly dubious "advantage".</p> + </dd> + <dt><a name="Entrust">Entrust</a></dt> + <dd>A Canadian company offerring enterprise <a href="#PKI">PKI</a> + products using <a href="#CAST128">CAST-128</a> symmetric crypto, <a + href="#RSA">RSA</a> public key and <a href="#X509">X.509</a> + directories. <a href="http://www.entrust.com">Web site</a></dd> + <dt><a name="EFF">EFF</a></dt> + <dd><a href="http://www.eff.org">Electronic Frontier Foundation</a>, an + advocacy group for civil rights in cyberspace.</dd> + <dt><a name="encryption">Encryption</a></dt> + <dd>Techniques for converting a readable message (<a + href="#plaintext">plaintext</a>) into apparently random material (<a + href="#ciphertext">ciphertext</a>) which cannot be read if intercepted. + A key is required to read the message. + <p>Major variants include <a href="#symmetric">symmetric</a> encryption + in which sender and receiver use the same secret key and <a + href="#public">public key</a> methods in which the sender uses one of a + matched pair of keys and the receiver uses the other. Many current + systems, including <a href="#IPSEC">IPsec</a>, are <a + href="#hybrid">hybrids</a> combining the two techniques.</p> + </dd> + <dt><a name="ESP">ESP</a></dt> + <dd><b>E</b>ncapsulated <b>S</b>ecurity <b>P</b>ayload, the <a + href="#IPSEC">IPsec</a> protocol which provides <a + href="#encryption">encryption</a>. It can also provide <a + href="#authentication">authentication</a> service and may be used with + null encryption (which we do not recommend). For details see our <a + href="ipsec.html#ESP.ipsec">IPsec</a> document and/or RFC 2406.</dd> + <dt><a name="#extruded">Extruded subnet</a></dt> + <dd>A situation in which something IP sees as one network is actually in + two or more places. + <p>For example, the Internet may route all traffic for a particular + company to that firm's corporate gateway. It then becomes the company's + problem to get packets to various machines on their <a + href="#subnet">subnets</a> in various departments. They may decide to + treat a branch office like a subnet, giving it IP addresses "on" their + corporate net. This becomes an extruded subnet.</p> + <p>Packets bound for it are delivered to the corporate gateway, since + as far as the outside world is concerned, that subnet is part of the + corporate network. However, instead of going onto the corporate LAN (as + they would for, say, the accounting department) they are then + encapsulated and sent back onto the Internet for delivery to the branch + office.</p> + <p>For information on doing this with Linux FreeS/WAN, look in our <a + href="adv_config.html#extruded.config">advanced configuration</a> + section.</p> + </dd> + <dt>Exhaustive search</dt> + <dd>See <a href="#brute">brute force attack</a>.</dd> + <dt><a name="F">F</a></dt> + <dt><a name="FIPS">FIPS</a></dt> + <dd><b>F</b>ederal <b>I</b>nformation <b>P</b>rocessing <b>S</b>tandard, + the US government's standards for products it buys. These are issued by + <a href="#NIST">NIST</a>. Among other things, <a href="#DES">DES</a> + and <a href="#SHA">SHA</a> are defined in FIPS documents. NIST have a + <a href="http://www.itl.nist.gov/div897/pubs">FIPS home page</a>.</dd> + <dt><a name="FSF">Free Software Foundation (FSF)</a></dt> + <dd>An organisation to promote free software, free in the sense of these + quotes from their web pages</dd> + <dd> + <blockquote> + "Free software" is a matter of liberty, not price. To understand the + concept, you should think of "free speech", not "free beer." + <p>"Free software" refers to the users' freedom to run, copy, + distribute, study, change and improve the software.</p> + </blockquote> + <p>See also <a href="#GNU">GNU</a>, <a href="#GPL">GNU General Public + License</a>, and <a href="http://www.fsf.org">the FSF site</a>.</p> + </dd> + <dt>FreeS/WAN</dt> + <dd>see <a href="#FreeSWAN">Linux FreeS/WAN</a></dd> + <dt><a name="fullnet">Fullnet</A></dt> + <dd>The CIDR block containing all IPs of its IP version. + The <A HREF="#IPv4">IPv4</A> fullnet is written 0.0.0.0/0. + Also known as "all" and "default", + fullnet may be used in a routing table + to specify a default route, + and in a FreeS/WAN + <A HREF="policygroups.html#policygroups">policy group</A> file to + specify a default IPsec policy.</dd> + <dt>FSF</dt> + <dd>see <a href="#FSF">Free software Foundation</a></dd> + <dt><a name="G">G</a></dt> + <dt><a name="GCHQ">GCHQ</a></dt> + <dd><a href="http://www.gchq.gov.uk">Government Communications + Headquarters</a>, the British organisation for <a + href="#SIGINT">signals intelligence</a>.</dd> + <dt>generator of a prime field</dt> + <dd>see <a href="#dlog">discrete logarithm problem</a></dd> + <dt><a name="GILC">GILC</a></dt> + <dd><a href="http://www.gilc.org">Global Internet Liberty Campaign</a>, + an international organisation advocating, among other things, free + availability of cryptography. They have a <a + href="http://www.gilc.org/crypto/wassenaar">campaign</a> to remove + cryptographic software from the <a href="#Wassenaar.gloss">Wassenaar + Arrangement</a>.</dd> + <dt>Global Internet Liberty Campaign</dt> + <dd>see <a href="#GILC">GILC</a>.</dd> + <dt><a name="GTR">Global Trust Register</a></dt> + <dd>An attempt to create something like a <a href="#rootCA">root CA</a> + for <a href="#PGP">PGP</a> by publishing both <a + href="biblio.html#GTR">as a book</a> and <a + href="http://www.cl.cam.ac.uk/Research/Security/Trust-Register"> on the + web</a> the fingerprints of a set of verified keys for well-known users + and organisations.</dd> + <dt><a name="GMP">GMP</a></dt> + <dd>The <b>G</b>NU <b>M</b>ulti-<b>P</b>recision library code, used in <a + href="#FreeSWAN">Linux FreeS/WAN</a> by <a href="#Pluto">Pluto</a> for + <a href="#public">public key</a> calculations. See the <a + href="http://www.swox.com/gmp">GMP home page</a>.</dd> + <dt><a name="GNU">GNU</a></dt> + <dd><b>G</b>NU's <b>N</b>ot <b>U</b>nix, the <a href="#FSF">Free Software + Foundation's</a> project aimed at creating a free system with at least + the capabilities of Unix. <a href="#Linux">Linux</a> uses GNU utilities + extensively.</dd> + <dt><a name="#GOST">GOST</a></dt> + <dd>a Soviet government standard <a href="#block">block cipher</a>. <a + href="biblio.html#schneier">Applied Cryptography</a> has details.</dd> + <dt>GPG</dt> + <dd>see <a href="#GPG">GNU Privacy Guard</a></dd> + <dt><a name="GPL">GNU General Public License</a>(GPL, copyleft)</dt> + <dd>The license developed by the <a href="#FSF">Free Software + Foundation</a> under which <a href="#Linux">Linux</a>, <a + href="#FreeSWAN">Linux FreeS/WAN</a> and many other pieces of software + are distributed. The license allows anyone to redistribute and modify + the code, but forbids anyone from distributing executables without + providing access to source code. For more details see the file <a + href="../COPYING">COPYING</a> included with GPLed source distributions, + including ours, or <a href="http://www.fsf.org/copyleft/gpl.html"> the + GNU site's GPL page</a>.</dd> + <dt><a name="GPG">GNU Privacy Guard</a></dt> + <dd>An open source implementation of Open <a href="#PGP">PGP</a> as + defined in RFC 2440. See their <a href="http://www.gnupg.org">web + site</a></dd> + <dt>GPL</dt> + <dd>see <a href="#GPL">GNU General Public License</a>.</dd> + <dt><a name="H">H</a></dt> + <dt><a name="hash">Hash</a></dt> + <dd>see <a href="#digest">message digest</a></dd> + <dt><a name="HMAC">Hashed Message Authentication Code (HMAC)</a></dt> + <dd>using keyed <a href="#digest">message digest</a> functions to + authenticate a message. This differs from other uses of these functions: + <ul> + <li>In normal usage, the hash function's internal variable are + initialised in some standard way. Anyone can reproduce the hash to + check that the message has not been altered.</li> + <li>For HMAC usage, you initialise the internal variables from the + key. Only someone with the key can reproduce the hash. A successful + check of the hash indicates not only that the message is unchanged + but also that the creator knew the key.</li> + </ul> + <p>The exact techniques used in <a href="#IPSEC">IPsec</a> are defined + in RFC 2104. They are referred to as HMAC-MD5-96 and HMAC-SHA-96 + because they output only 96 bits of the hash. This makes some attacks + on the hash functions harder.</p> + </dd> + <dt>HMAC</dt> + <dd>see <a href="#HMAC">Hashed Message Authentication Code</a></dd> + <dt>HMAC-MD5-96</dt> + <dd>see <a href="#HMAC">Hashed Message Authentication Code</a></dd> + <dt>HMAC-SHA-96</dt> + <dd>see <a href="#HMAC">Hashed Message Authentication Code</a></dd> + <dt><a name="hybrid">Hybrid cryptosystem</a></dt> + <dd>A system using both <a href="#public">public key</a> and <a + href="#symmetric">symmetric cipher</a> techniques. This works well. + Public key methods provide key management and <a + href="#signature">digital signature</a> facilities which are not + readily available using symmetric ciphers. The symmetric cipher, + however, can do the bulk of the encryption work much more efficiently + than public key methods.</dd> + <dt><a name="I">I</a></dt> + <dt><a name="IAB">IAB</a></dt> + <dd><a href="http://www.iab.org/iab">Internet Architecture Board</a>.</dd> + <dt><a name="ICMP.gloss">ICMP</a></dt> + <dd><strong>I</strong>nternet <strong>C</strong>ontrol + <strong>M</strong>essage <strong>P</strong>rotocol. This is used for + various IP-connected devices to manage the network.</dd> + <dt><a name="IDEA">IDEA</a></dt> + <dd><b>I</b>nternational <b>D</b>ata <b>E</b>ncrypion <b>A</b>lgorithm, + developed in Europe as an alternative to exportable American ciphers + such as <a href="#DES">DES</a> which were <a href="#desnotsecure">too + weak for serious use</a>. IDEA is a <a href="#block">block cipher</a> + using 64-bit blocks and 128-bit keys, and is used in products such as + <a href="#PGP">PGP</a>. + <p>IDEA is not required by the <a href="#IPSEC">IPsec</a> RFCs and not + currently used in <a href="#FreeSWAN">Linux FreeS/WAN</a>.</p> + <p>IDEA is patented and, with strictly limited exceptions for personal + use, using it requires a license from <a + href="http://www.ascom.com">Ascom</a>.</p> + </dd> + <dt><a name="IEEE">IEEE</a></dt> + <dd><a href="http://www.ieee.org">Institute of Electrical and Electronic + Engineers</a>, a professional association which, among other things, + sets some technical standards</dd> + <dt><a name="IESG">IESG</a></dt> + <dd><a href="http://www.iesg.org">Internet Engineering Steering + Group</a>.</dd> + <dt><a name="IETF">IETF</a></dt> + <dd><a href="http://www.ietf.org">Internet Engineering Task Force</a>, + the umbrella organisation whose various working groups make most of the + technical decisions for the Internet. The IETF <a + href="http://www.ietf.org/html.charters/ipsec-charter.html"> IPsec + working group</a> wrote the <a href="#RFC">RFCs</a> we are + implementing.</dd> + <dt><a name="IKE">IKE</a></dt> + <dd><b>I</b>nternet <b>K</b>ey <b>E</b>xchange, based on the <a + href="#DH">Diffie-Hellman</a> key exchange protocol. For details, see + RFC 2409 and our <a href="ipsec.html">IPsec</a> document. IKE is + implemented in <a href="#FreeSWAN">Linux FreeS/WAN</a> by the <a + href="#Pluto">Pluto daemon</a>.</dd> + <dt>IKE v2</dt> + <dd>A proposed replacement for <a href="#IKE">IKE</a>. There are other + candidates, such as <a href="#JFK">JFK</a>, and at time of writing + (March 2002) the choice between them has not yet been made and does not + appear imminent.</dd> + <dt><a name="iOE">iOE</a></dt> + <dd>See <A HREF="#initiate-only">Initiate-only opportunistic + encryption</A>.</dd> + <dt><a name="IP">IP</a></dt> + <dd><b>I</b>nternet <b>P</b>rotocol.</dd> + <dt><a name="masq">IP masquerade</a></dt> + <dd>A mostly obsolete term for a method of allowing multiple machines to + communicate over the Internet when only one IP address is available for + their use. The more current term is Network Address Translation or <a + href="#NAT.gloss">NAT</a>.</dd> + <dt><a name="IPng">IPng</a></dt> + <dd>"IP the Next Generation", see <a href="#ipv6.gloss">IPv6</a>.</dd> + <dt><a name="IPv4">IPv4</a></dt> + <dd>The current version of the <a href="#IP">Internet protocol + suite</a>.</dd> + <dt><a name="ipv6.gloss">IPv6 (IPng)</a></dt> + <dd>Version six of the <a href="#IP">Internet protocol suite</a>, + currently being developed. It will replace the current <a + href="#IPv4">version four</a>. IPv6 has <a href="#IPSEC">IPsec</a> as a + mandatory component. + <p>See this <a + href="http://playground.sun.com/pub/ipng/html/ipng-main.html">web + site</a> for more details, and our <a + href="compat.html#ipv6">compatibility</a> document for information on + FreeS/WAN and the Linux implementation of IPv6.</p> + </dd> + <dt><a name="IPSEC">IPsec</a> or IPSEC</dt> + <dd><b>I</b>nternet <b>P</b>rotocol <b>SEC</b>urity, security functions + (<a href="#authentication">authentication</a> and <a + href="#encryption">encryption</a>) implemented at the IP level of the + protocol stack. It is optional for <a href="#IPv4">IPv4</a> and + mandatory for <a href="#ipv6.gloss">IPv6</a>. + <p>This is the standard <a href="#FreeSWAN">Linux FreeS/WAN</a> is + implementing. For more details, see our <a href="ipsec.html">IPsec + Overview</a>. For the standards, see RFCs listed in our <a + href="rfc.html#RFC">RFCs document</a>.</p> + </dd> + <dt><a name="IPX">IPX</a></dt> + <dd>Novell's Netware protocol tunnelled over an IP link. Our <a + href="firewall.html#user.scripts">firewalls</a> document includes an + example of using this through an IPsec tunnel.</dd> + <dt><a name="ISAKMP">ISAKMP</a></dt> + <dd><b>I</b>nternet <b>S</b>ecurity <b>A</b>ssociation and <b>K</b>ey + <b>M</b>anagement <b>P</b>rotocol, defined in RFC 2408.</dd> + <dt><a name="ITAR">ITAR</a></dt> + <dd><b>I</b>nternational <b>T</b>raffic in <b>A</b>rms + <b>R</b>egulations, US regulations administered by the State Department + which until recently limited export of, among other things, + cryptographic technology and software. ITAR still exists, but the + limits on cryptography have now been transferred to the <a + href="#EAR">Export Administration Regulations</a> under the Commerce + Department's <a href="#BXA">Bureau of Export Administration</a>.</dd> + <dt>IV</dt> + <dd>see <a href="#IV">Initialisation vector</a></dd> + <dt><a name="IV">Initialisation Vector (IV)</a></dt> + <dd>Some cipher <a href="#mode">modes</a>, including the <a + href="#CBC">CBC</a> mode which IPsec uses, require some extra data at + the beginning. This data is called the initialisation vector. It need + not be secret, but should be different for each message. Its function + is to prevent messages which begin with the same text from encrypting + to the same ciphertext. That might give an analyst an opening, so it is + best prevented.</dd> + <dt><a name="initiate-only">Initiate-only opportunistic + encryption (iOE)</a></dt> + <dd>A form of + <A HREF="#carpediem">opportunistic encryption</A> (OE) in which + a host proposes opportunistic connections, but lacks the reverse DNS + records necessary to support incoming opportunistic connection requests. + Common among hosts on cable or pppoe connections where the system + administrator does not have write access to the DNS reverse map + for the host's external IP. + <p>Configuring for initiate-only opportunistic encryption + is described in our + <a href="quickstart.html#opp.client">quickstart</a> document.</p> + </dd> + <dt><a name="J">J</a></dt> + <dt><a name="JFK">JFK</a></dt> + <dd><strong>J</strong>ust <strong>F</strong>ast <strong>K</strong>eying, + a proposed simpler replacement for <a href="#IKE">IKE.</a></dd> + <dt><a name="K">K</a></dt> + <dt><a name="kernel">Kernel</a></dt> + <dd>The basic part of an operating system (e.g. Linux) which controls the + hardware and provides services to all other programs. + <p>In the Linux release numbering system, an even second digit as in + 2.<strong>2</strong>.x indicates a stable or production kernel while an + odd number as in 2.<strong>3</strong>.x indicates an experimental or + development kernel. Most users should run a recent kernel version from + the production series. The development kernels are primarily for people + doing kernel development. Others should consider using development + kernels only if they have an urgent need for some feature not yet + available in production kernels.</p> + </dd> + <dt>Keyed message digest</dt> + <dd>See <a href="#HMAC">HMAC</a>.</dd> + <dt>Key length</dt> + <dd>see <a href="#brute">brute force attack</a></dd> + <dt><a name="KLIPS">KLIPS</a></dt> + <dd><b>K</b>erne<b>l</b> <b>IP</b> <b>S</b>ecurity, the <a + href="#FreeSWAN">Linux FreeS/WAN</a> project's changes to the <a + href="#Linux">Linux</a> kernel to support the <a + href="#IPSEC">IPsec</a> protocols.</dd> + <dt><a name="L">L</a></dt> + <dt><a name="LDAP">LDAP</a></dt> + <dd><b>L</b>ightweight <b>D</b>irectory <b>A</b>ccess <b>P</b>rotocol, + defined in RFCs 1777 and 1778, a method of accessing information + stored in directories. LDAP is used by several <a href="#PKI">PKI</a> + implementations, often with X.501 directories and <a + href="#X509">X.509</a> certificates. It may also be used by <a + href="#IPSEC">IPsec</a> to obtain key certifications from those PKIs. + This is not yet implemented in <a href="#FreeSWAN">Linux + FreeS/WAN</a>.</dd> + <dt><a name="LIBDES">LIBDES</a></dt> + <dd>A publicly available library of <a href="#DES">DES</a> code, written + by Eric Young, which <a href="#FreeSWAN">Linux FreeS/WAN</a> uses in + both <a href="#KLIPS">KLIPS</a> and <a href="#Pluto">Pluto</a>.</dd> + <dt><a name="Linux">Linux</a></dt> + <dd>A freely available Unix-like operating system based on a kernel + originally written for the Intel 386 architecture by (then) student + Linus Torvalds. Once his 32-bit kernel was available, the <a + href="#GNU">GNU</a> utilities made it a usable system and contributions + from many others led to explosive growth. + <p>Today Linux is a complete Unix replacement available for several CPU + architectures -- Intel, DEC/Compaq Alpha, Power PC, both 32-bit SPARC + and the 64-bit UltraSPARC, SrongARM, . . . -- with support for multiple + CPUs on some architectures.</p> + <p><a href="#FreeSWAN">Linux FreeS/WAN</a> is intended to run on all + CPUs supported by Linux and is known to work on several. See our <a + href="compat.html#CPUs">compatibility</a> section for a list.</p> + </dd> + <dt><a name="FreeSWAN">Linux FreeS/WAN</a></dt> + <dd>Our implementation of the <a href="#IPSEC">IPsec</a> protocols, + intended to be freely redistributable source code with <a href="#GPL">a + GNU GPL license</a> and no constraints under US or other <a + href="politics.html#exlaw">export laws</a>. Linux FreeS/WAN is intended + to interoperate with other <a href="#IPSEC">IPsec</a> implementations. + The name is partly taken, with permission, from the <a + href="#SWAN">S/WAN</a> multi-vendor IPsec compatability effort. Linux + FreeS/WAN has two major components, <a href="#KLIPS">KLIPS</a> (KerneL + IPsec Support) and the <a href="#Pluto">Pluto</a> daemon which manages + the whole thing. + <p>See our <a href="ipsec.html">IPsec section</a> for more detail. For + the code see our <a href="http://freeswan.org"> primary site</a> or one + of the mirror sites on <a href="intro.html#mirrors">this list</a>.</p> + </dd> + <dt><a name="LSM">Linux Security Modules (LSM)</a></dt> + <dd>a project to create an interface in the Linux kernel that supports + plug-in modules for various security policies. + <p>This allows multiple security projects to take different approaches + to security enhancement without tying the kernel down to one particular + approach. As I understand the history, several projects were pressing + Linus to incorporate their changes, the various sets of changes were + incompatible, and his answer was more-or-less "a plague on all your + houses; I'll give you an interface, but I won't incorporate + anything".</p> + <p>It seems to be working. There is a fairly active <a + href="http://mail.wirex.com/mailman/listinfo/linux-security-module">LSM + mailing list</a>, and several projects are already using the + interface.</p> + </dd> + <dt>LSM</dt> + <dd>see <a href="#LSM">Linux Security Modules</a></dd> + <dt><a name="M">M</a></dt> + <dt><a name="list">Mailing list</a></dt> + <dd>The <a href="#FreeSWAN">Linux FreeS/WAN</a> project has several + public email lists for bug reports and software development + discussions. See our document on <a href="mail.html">mailing + lists</a>.</dd> + <dt><a name="middle">Man-in-the-middle attack</a></dt> + <dd>An <a href="#active">active attack</a> in which the attacker + impersonates each of the legitimate players in a protocol to the other. + <p>For example, if <a href="#alicebob">Alice and Bob</a> are + negotiating a key via the <a href="#DH">Diffie-Hellman</a> key + agreement, and are not using <a + href="#authentication">authentication</a> to be certain they are + talking to each other, then an attacker able to insert himself in the + communication path can deceive both players.</p> + <p>Call the attacker Mallory. For Bob, he pretends to be Alice. For + Alice, he pretends to be Bob. Two keys are then negotiated, + Alice-to-Mallory and Bob-to-Mallory. Alice and Bob each think the key + they have is Alice-to-Bob.</p> + <p>A message from Alice to Bob then goes to Mallory who decrypts it, + reads it and/or saves a copy, re-encrypts using the Bob-to-Mallory key + and sends it along to Bob. Bob decrypts successfully and sends a reply + which Mallory decrypts, reads, re-encrypts and forwards to Alice.</p> + <p>To make this attack effective, Mallory must</p> + <ul> + <li>subvert some part of the network in some way that lets him carry + out the deception<br> + possible targets: DNS, router, Alice or Bob's machine, mail server, + ...</li> + <li>beat any authentication mechanism Alice and Bob use<br> + strong authentication defeats the attack entirely; this is why <a + href="#IKE">IKE</a> requires authentication</li> + <li>work in real time, delivering messages without introducing a + delay large enough to alert the victims<br> + not hard if Alice and Bob are using email; quite difficult in some + situations.</li> + </ul> + <p>If he manages it, however, it is devastating. He not only gets to + read all the messages; he can alter messages, inject his own, forge + anything he likes, . . . In fact, he controls the communication + completely.</p> + </dd> + <dt><a name="mandatory">mandatory access control</a></dt> + <dd>access control mechanisims which are not settable by the user (see <a + href="#discretionary">discretionary access control</a>), but are + enforced by the system. + <p>For example, a document labelled "secret, zebra" might be readable + only by someone with secret clearance working on Project Zebra. + Ideally, the system will prevent any transfer outside those boundaries. + For example, even if you can read it, you should not be able to e-mail + it (unless the recipient is appropriately cleared) or print it (unless + certain printers are authorised for that classification).</p> + <p>Mandatory access control is a required feature for some levels of <a + href="#rainbow">Rainbow Book</a> or <a href="#cc">Common Criteria</a> + classification, but has not been widely used outside the military and + government. There is a good discussion of the issues in Anderson's <a + href="biblio.html#anderson">Security Engineering</a>.</p> + <p>The <a href="#SElinux">Security Enhanced Linux</a> project is adding + mandatory access control to Linux.</p> + </dd> + <dt><a name="manual">Manual keying</a></dt> + <dd>An IPsec mode in which the keys are provided by the administrator. In + FreeS/WAN, they are stored in /etc/ipsec.conf. The alternative, <a + href="#auto">automatic keying</a>, is preferred in most cases. See this + <a href="adv_config.html#man-auto">discussion</a>.</dd> + <dt><a name="MD4">MD4</a></dt> + <dd><a href="#digest">Message Digest Algorithm</a> Four from Ron Rivest + of <a href="#RSAco">RSA</a>. MD4 was widely used a few years ago, but + is now considered obsolete. It has been replaced by its descendants <a + href="#MD5">MD5</a> and <a href="#SHA">SHA</a>.</dd> + <dt><a name="MD5">MD5</a></dt> + <dd><a href="#digest">Message Digest Algorithm</a> Five from Ron Rivest + of <a href="#RSAco">RSA</a>, an improved variant of his <a + href="#MD4">MD4</a>. Like MD4, it produces a 128-bit hash. For details + see RFC 1321. + <p>MD5 is one of two message digest algorithms available in IPsec. The + other is <a href="#SHA">SHA</a>. SHA produces a longer hash and is + therefore more resistant to <a href="#birthday">birthday attacks</a>, + but this is not a concern for IPsec. The <a href="#HMAC">HMAC</a> + method used in IPsec is secure even if the underlying hash is not + particularly strong against this attack.</p> + <p>Hans Dobbertin found a weakness in MD5, and people often ask whether + this means MD5 is unsafe for IPsec. It doesn't. The IPsec RFCs discuss + Dobbertin's attack and conclude that it does not affect MD5 as used for + HMAC in IPsec.</p> + </dd> + <dt><a name="meet">Meet-in-the-middle attack</a></dt> + <dd>A divide-and-conquer attack which breaks a cipher into two parts, + works against each separately, and compares results. Probably the best + known example is an attack on double DES. This applies in principle to + any pair of block ciphers, e.g. to an encryption system using, say, + CAST-128 and Blowfish, but we will describe it for double DES. + <p>Double DES encryption and decryption can be written:</p> + <pre> C = E(k2,E(k1,P)) + P = D(k1,D(k2,C))</pre> + <p>Where C is ciphertext, P is plaintext, E is encryption, D is + decryption, k1 is one key, and k2 is the other key. If we know a P, C + pair, we can try and find the keys with a brute force attack, trying + all possible k1, k2 pairs. Since each key is 56 bits, there are + 2<sup>112</sup> such pairs and this attack is painfully inefficient.</p> + <p>The meet-in-the middle attack re-writes the equations to calculate a + middle value M:</p> + <pre> M = E(k1,P) + M = D(k2,C)</pre> + <p>Now we can try some large number of D(k2,C) decryptions with various + values of k2 and store the results in a table. Then start doing E(k1,P) + encryptions, checking each result to see if it is in the table.</p> + <p>With enough table space, this breaks double DES with + <nobr>2<sup>56</sup> + 2<sup>56</sup> = 2<sup>57</sup></nobr>work. + Against triple DES, you need <nobr>2<sup>56</sup> + 2<sup>112</sup> ~= + 2<sup>112</sup></nobr>.</p> + <p>The memory requirements for such attacks can be prohibitive, but + there is a whole body of research literature on methods of reducing + them.</p> + </dd> + <dt><a name="digest">Message Digest Algorithm</a></dt> + <dd>An algorithm which takes a message as input and produces a hash or + digest of it, a fixed-length set of bits which depend on the message + contents in some highly complex manner. Design criteria include making + it extremely difficult for anyone to counterfeit a digest or to change + a message without altering its digest. One essential property is <a + href="#collision">collision resistance</a>. The main applications are + in message <a href="#authentication">authentication</a> and <a + href="#signature">digital signature</a> schemes. Widely used algorithms + include <a href="#MD5">MD5</a> and <a href="#SHA">SHA</a>. In IPsec, + message digests are used for <a href="#HMAC">HMAC</a> authentication of + packets.</dd> + <dt><a name="MTU">MTU</a></dt> + <dd><strong>M</strong>aximum <strong>T</strong>ransmission + <strong>U</strong>nit, the largest size of packet that can be sent over + a link. This is determined by the underlying network, but must be taken + account of at the IP level. + <p>IP packets, which can be up to 64K bytes each, must be packaged into + lower-level packets of the appropriate size for the underlying + network(s) and re-assembled on the other end. When a packet must pass + over multiple networks, each with its own MTU, and many of the MTUs are + unknown to the sender, this becomes a fairly complex problem. See <a + href="#pathMTU">path MTU discovery</a> for details.</p> + <p>Often the MTU is a few hundred bytes on serial links and 1500 on + Ethernet. There are, however, serial link protocols which use a larger + MTU to avoid fragmentation at the ethernet/serial boundary, and newer + (especially gigabit) Ethernet networks sometimes support much larger + packets because these are more efficient in some applications.</p> + </dd> + <dt><a name="N">N</a></dt> + <dt><a name="NAI">NAI</a></dt> + <dd><a href="http://www.nai.com">Network Associates</a>, a conglomerate + formed from <a href="#PGPI">PGP Inc.</a>, TIS (Trusted Information + Systems, a firewall vendor) and McAfee anti-virus products. Among other + things, they offer an IPsec-based VPN product.</dd> + <dt><a name="NAT.gloss">NAT</a></dt> + <dd><b>N</b>etwork <b>A</b>ddress <b>T</b>ranslation, a process by which + firewall machines may change the addresses on packets as they go + through. For discussion, see our <a + href="background.html#nat.background">background</a> section.</dd> + <dt><a name="NIST">NIST</a></dt> + <dd>The US <a href="http://www.nist.gov"> National Institute of Standards + and Technology</a>, responsible for <a href="#FIPS">FIPS standards</a> + including <a href="#DES">DES</a> and its replacement, <a + href="#AES">AES</a>.</dd> + <dt><a name="nonce">Nonce</a></dt> + <dd>A <a href="#random">random</a> value used in an <a + href="#authentication">authentication</a> protocol.</dd> + <dt></dt> + <dt><a name="non-routable">Non-routable IP address</a></dt> + <dd>An IP address not normally allowed in the "to" or "from" IP address + field header of IP packets. + <p>Almost invariably, the phrase "non-routable address" means one of + the addresses reserved by RFC 1918 for private networks:</p> + <ul> + <li>10.anything</li> + <li>172.x.anything with 16 <= x <= 31</li> + <li>192.168.anything</li> + </ul> + <p>These addresses are commonly used on private networks, e.g. behind a + Linux machines doing <a href="#masq">IP masquerade</a>. Machines within + the private network can address each other with these addresses. All + packets going outside that network, however, have these addresses + replaced before they reach the Internet.</p> + <p>If any packets using these addresses do leak out, they do not go + far. Most routers automatically discard all such packets.</p> + <p>Various other addresses -- the 127.0.0.0/8 block reserved for local + use, 0.0.0.0, various broadcast and network addresses -- cannot be + routed over the Internet, but are not normally included in the meaning + when the phrase "non-routable address" is used.</p> + </dd> + <dt><a name="NSA">NSA</a></dt> + <dd>The US <a href="http://www.nsa.gov"> National Security Agency</a>, + the American organisation for <a href="#SIGINT">signals + intelligence</a>, the protection of US government messages and the + interception and analysis of other messages. For details, see Bamford's + <a href="biblio.html#puzzle">"The Puzzle Palace"</a>. + <p>Some <a + href="http://www.gwu.edu/~nsarchiv/NSAEBB/NSAEBB23/index.html">history + of NSA</a> documents were declassified in response to a FOIA (Freedom + of Information Act) request.</p> + </dd> + <dt><a name="O">O</a></dt> + <dt><a name="oakley">Oakley</a></dt> + <dd>A key determination protocol, defined in RFC 2412.</dd> + <dt>Oakley groups</dt> + <dd>The groups used as the basis of <a href="#DH">Diffie-Hellman</a> key + exchange in the Oakley protocol, and in <a href="#IKE">IKE</a>. Four + were defined in the original RFC, and a fifth has been <a + href="http://www.lounge.org/ike_doi_errata.html">added since</a>. + <p>Linux FreeS/WAN currently supports the three groups based on finite + fields modulo a prime (Groups 1, 2 and 5) and does not support the + elliptic curve groups (3 and 4). For a description of the difference of + the types, see <a href="#dlog">discrete logarithms</a>.</p> + </dd> + <dt><a name="OTP">One time pad</a></dt> + <dd>A cipher in which the key is: + <ul> + <li>as long as the total set of messages to be enciphered</li> + <li>absolutely <a href="#random">random</a></li> + <li>never re-used</li> + </ul> + <p>Given those three conditions, it can easily be proved that the + cipher is perfectly secure, in the sense that an attacker with + intercepted message in hand has no better chance of guessing the + message than an attacker who has not intercepted the message and only + knows the message length. No such proof exists for any other cipher.</p> + <p>There are, however, several problems with this "perfect" cipher.</p> + <p>First, it is <strong>wildly impractical</strong> for most + applications. Key management is at best difficult, often completely + impossible.</p> + <p>Second, it is <strong>extremely fragile</strong>. Small changes + which violate the conditions listed above do not just weaken the cipher + liitle. Quite often they destroy its security completely.</p> + <ul> + <li>Re-using the pad weakens the cipher to the point where it can be + broken with pencil and paper. With a computer, the attack is + trivially easy.</li> + <li>Using <em>anything</em> less than truly <a + href="#random">random</a> numbers <em>completely</em> invalidates + the security proof.</li> + <li>In particular, using computer-generated pseudo-random numbers may + give an extremely weak cipher. It might also produce a good stream + cipher, if the pseudo-random generator is both well-designed and + properely seeded.</li> + </ul> + <p>Marketing claims about the "unbreakable" security of various + products which somewhat resemble one-time pads are common. Such claims + are one of the surest signs of cryptographic <a href="#snake">snake + oil</a>; most systems marketed with such claims are worthless.</p> + <p>Finally, even if the system is implemented and used correctly, it is + <strong>highly vulnerable to a substitution attack</strong>. If an + attacker knows some plaintext and has an intercepted message, he can + discover the pad.</p> + <ul> + <li>This does not matter if the attacker is just a <a + href="#passive">passive</a> eavesdropper. It gives him no plaintext + he didn't already know and we don't care that he learns a pad which + we will never re-use.</li> + <li>However, an <a href="#active">active</a> attacker who knows the + plaintext can recover the pad, then use it to encode with whatever + he chooses. If he can get his version delivered instead of yours, + this may be a disaster. If you send "attack at dawn", the delivered + message can be anything the same length -- perhaps "retreat to + east" or "shoot generals".</li> + <li>An active attacker with only a reasonable guess at the plaintext + can try the same attack. If the guess is correct, this works and + the attacker's bogus message is delivered. If the guess is wrong, a + garbled message is delivered.</li> + </ul> + <p>In general then, despite its theoretical perfection, the + one-time-pad has very limited practical application.</p> + <p>See also the <a href="http://pubweb.nfr.net/~mjr/pubs/otpfaq/">one + time pad FAQ</a>.</p> + </dd> + <dt><a name="carpediem">Opportunistic encryption (OE)</a></dt> + <dd>A situation in which any two IPsec-aware machines can secure their + communications, without a pre-shared secret and without a common <a + href="#PKI">PKI</a> or previous exchange of public keys. This is one of + the goals of the Linux FreeS/WAN project, discussed in our <a + href="intro.html#goals">introduction</a> section. + <p>Setting up for opportunistic encryption is described in our <a + href="quickstart.html#quickstart">quickstart</a> document.</p> + </dd> + <dt><a name="responder">Opportunistic responder</a></dt> + <dd>A host which accepts, but does not initiate, requests for + <A HREF="#carpediem">opportunistic encryption</A> (OE). + An opportunistic responder has enabled OE in its + <A HREF="#passive.OE">passive</A> form (pOE) only. + A web server or file server may be usefully set up as an opportunistic + responder. + <p>Configuring passive OE is described in our + <a href="policygroups.html#policygroups">policy groups</a> document.</p> + </dd> + <dt><a name="orange">Orange book</a></dt> + <dd>the most basic and best known of the US government's <a + href="#rainbow">Rainbow Book</a> series of computer security + standards.</dd> + <dt><a name="P">P</a></dt> + <dt><a name="P1363">P1363 standard</a></dt> + <dd>An <a href="#IEEE">IEEE</a> standard for public key cryptography. <a + href="http://grouper.ieee.org/groups/1363">Web page</a>.</dd> + <dt><a name="pOE">pOE</a></dt> + <dd>See <a href="#passive.OE">Passive opportunistic encryption</a>.</dd> + <dt><a name="passive">Passive attack</a></dt> + <dd>An attack in which the attacker only eavesdrops and attempts to + analyse intercepted messages, as opposed to an <a href="#active">active + attack</a> in which he diverts messages or generates his own.</dd> + <dt><a name="passive.OE">Passive opportunistic encryption (pOE)</a></dt> + <dd>A form of + <A HREF="#carpediem">opportunistic encryption</A> (OE) in which the + host will accept opportunistic connection requests, but will not + initiate such requests. A host which runs OE in its passive form only + is known as an <A HREF="#responder">opportunistic responder</A>. + <p>Configuring passive OE is described in our + <a href="policygroups.html#policygroups">policy groups</a> document.</p> + </dd> + <dt><a name="pathMTU">Path MTU discovery</a></dt> + <dd>The process of discovering the largest packet size which all links on + a path can handle without fragmentation -- that is, without any router + having to break the packet up into smaller pieces to match the <a + href="#MTU">MTU</a> of its outgoing link. + <p>This is done as follows:</p> + <ul> + <li>originator sends the largest packets allowed by <a + href="#MTU">MTU</a> of the first link, setting the DF + (<strong>d</strong>on't <strong>f</strong>ragment) bit in the + packet header</li> + <li>any router which cannot send the packet on (outgoing MTU is too + small for it, and DF prevents fragmenting it to match) sends back + an <a href="#ICMP.gloss">ICMP</a> packet reporting the problem</li> + <li>originator looks at ICMP message and tries a smaller size</li> + <li>eventually, you settle on a size that can pass all routers</li> + <li>thereafter, originator just sends that size and no-one has to + fragment</li> + </ul> + <p>Since this requires co-operation of many systems, and since the next + packet may travel a different path, this is one of the trickier areas + of IP programming. Bugs that have shown up over the years have + included:</p> + <ul> + <li>malformed ICMP messages</li> + <li>hosts that ignore or mishandle these ICMP messages</li> + <li>firewalls blocking the ICMP messages so host does not see + them</li> + </ul> + <p>Since IPsec adds a header, it increases packet size and may require + fragmentation even where incoming and outgoing MTU are equal.</p> + </dd> + <dt><a name="PFS">Perfect forward secrecy (PFS)</a></dt> + <dd>A property of systems such as <a href="#DH">Diffie-Hellman</a> key + exchange which use a long-term key (such as the shared secret in IKE) + and generate short-term keys as required. If an attacker who acquires + the long-term key <em>provably</em> can + <ul> + <li><em>neither</em> read previous messages which he may have + archived</li> + <li><em>nor</em> read future messages without performing additional + successful attacks</li> + </ul> + <p>then the system has PFS. The attacker needs the short-term keys in + order to read the trafiic and merely having the long-term key does not + allow him to infer those. Of course, it may allow him to conduct + another attack (such as <a href="#middle">man-in-the-middle</a>) which + gives him some short-term keys, but he does not automatically get them + just by acquiring the long-term key.</p> + <p>See also +<a href="http://sandelman.ottawa.on.ca/ipsec/1996/08/msg00123.html">Phil +Karn's definition</a>. + </dd> + <dt>PFS</dt> + <dd>see Perfect Forward Secrecy</dd> + <dt><a name="PGP">PGP</a></dt> + <dd><b>P</b>retty <b>G</b>ood <b>P</b>rivacy, a personal encryption + system for email based on public key technology, written by Phil + Zimmerman. + <p>The 2.xx versions of PGP used the <a href="#RSA">RSA</a> public key + algorithm and used <a href="#IDEA">IDEA</a> as the symmetric cipher. + These versions are described in RFC 1991 and in <a + href="#PGP">Garfinkel's book</a>. Since version 5, the products from <a + href="#PGPI">PGP Inc</a>. have used <a href="#DH">Diffie-Hellman</a> + public key methods and <a href="#CAST128">CAST-128</a> symmetric + encryption. These can verify signatures from the 2.xx versions, but + cannot exchange encryted messages with them.</p> + <p>An <a href="#IETF">IETF</a> working group has issued RFC 2440 for an + "Open PGP" standard, similar to the 5.x versions. PGP Inc. staff were + among the authors. A free <a href="#GPG">Gnu Privacy Guard</a> based on + that standard is now available.</p> + <p>For more information on PGP, including how to obtain it, see our + cryptography <a href="web.html#tools">links</a>.</p> + </dd> + <dt><a name="PGPI">PGP Inc.</a></dt> + <dd>A company founded by Zimmerman, the author of <a href="#PGP">PGP</a>, + now a division of <a href="#NAI">NAI</a>. See the <a + href="http://www.pgp.com">corporate website</a>. Zimmerman left in + 2001, and early in 2002 NAI announced that they would no longer sell + PGP.. + <p>Versions 6.5 and later of the PGP product include PGPnet, an IPsec + client for Macintosh or for Windows 95/98/NT. See our <a + href="interop.html#pgpnet">interoperation documen</a>t.</p> + </dd> + <dt><a name="photuris">Photuris</a></dt> + <dd>Another key negotiation protocol, an alternative to <a + href="#IKE">IKE</a>, described in RFCs 2522 and 2523.</dd> + <dt><a name="PPP">PPP</a></dt> + <dd><b>P</b>oint-to-<b>P</b>oint <b>P</b>rotocol, originally a method of + connecting over modems or serial lines, but see also PPPoE.</dd> + <dt><a name="PPPoE">PPPoE</a></dt> + <dd><b>PPP</b> <b>o</b>ver <b>E</b>thernet, a somewhat odd protocol that + makes Ethernet look like a point-to-point serial link. It is widely + used for cable or ADSL Internet services, apparently mainly because it + lets the providers use access control and address assignmment + mechanisms developed for dialup networks. <a + href="http://www.roaringpenguin.com">Roaring Penguin</a> provide a + widely used Linux implementation.</dd> + <dt><a name="PPTP">PPTP</a></dt> + <dd><b>P</b>oint-to-<b>P</b>oint <b>T</b>unneling <b>P</b>rotocol, used + in some Microsoft VPN implementations. Papers discussing weaknesses in + it are on <a + href="http://www.counterpane.com/publish.html">counterpane.com</a>. It + is now largely obsolete, replaced by L2TP.</dd> + <dt><a name="PKI">PKI</a></dt> + <dd><b>P</b>ublic <b>K</b>ey <b>I</b>nfrastructure, the things an + organisation or community needs to set up in order to make <a + href="#public">public key</a> cryptographic technology a standard part + of their operating procedures. + <p>There are several PKI products on the market. Typically they use a + hierarchy of <a href="#CA">Certification Authorities (CAs)</a>. Often + they use <a href="#LDAP">LDAP</a> access to <a href="#X509">X.509</a> + directories to implement this.</p> + <p>See <a href="#web">Web of Trust</a> for a different sort of + infrastructure.</p> + </dd> + <dt><a name="PKIX">PKIX</a></dt> + <dd><b>PKI</b> e<b>X</b>change, an <a href="#IETF">IETF</a> standard that + allows <a href="#PKI">PKI</a>s to talk to each other. + <p>This is required, for example, when users of a corporate PKI need to + communicate with people at client, supplier or government + organisations, any of which may have a different PKI in place. I should + be able to talk to you securely whenever:</p> + <ul> + <li>your organisation and mine each have a PKI in place</li> + <li>you and I are each set up to use those PKIs</li> + <li>the two PKIs speak PKIX</li> + <li>the configuration allows the conversation</li> + </ul> + <p>At time of writing (March 1999), this is not yet widely implemented + but is under quite active development by several groups.</p> + </dd> + <dt><a name="plaintext">Plaintext</a></dt> + <dd>The unencrypted input to a cipher, as opposed to the encrypted <a + href="#ciphertext">ciphertext</a> output.</dd> + <dt><a name="Pluto">Pluto</a></dt> + <dd>The <a href="#FreeSWAN">Linux FreeS/WAN</a> daemon which handles key + exchange via the <a href="#IKE">IKE</a> protocol, connection + negotiation, and other higher-level tasks. Pluto calls the <a + href="#KLIPS">KLIPS</a> kernel code as required. For details, see the + manual page ipsec_pluto(8).</dd> + <dt><a name="public">Public Key Cryptography</a></dt> + <dd>In public key cryptography, keys are created in matched pairs. + Encrypt with one half of a pair and only the matching other half can + decrypt it. This contrasts with <a href="#symmetric">symmetric or + secret key cryptography</a> in which a single key known to both parties + is used for both encryption and decryption. + <p>One half of each pair, called the public key, is made public. The + other half, called the private key, is kept secret. Messages can then + be sent by anyone who knows the public key to the holder of the private + key. Encrypt with the public key and you know that only someone with + the matching private key can decrypt.</p> + <p>Public key techniques can be used to create <a + href="#signature">digital signatures</a> and to deal with key + management issues, perhaps the hardest part of effective deployment of + <a href="#symmetric"> symmetric ciphers</a>. The resulting <a + href="#hybrid">hybrid cryptosystems</a> use public key methods to + manage keys for symmetric ciphers.</p> + <p>Many organisations are currently creating <a href="#PKI">PKIs, + public key infrastructures</a> to make these benefits widely + available.</p> + </dd> + <dt>Public Key Infrastructure</dt> + <dd>see <a href="#PKI">PKI</a></dd> + <dt><a name="Q">Q</a></dt> + <dt><a name="R">R</a></dt> + <dt><a name="rainbow">Rainbow books</a></dt> + <dd>A set of US government standards for evaluation of "trusted computer + systems", of which the best known was the <a href="#orange">Orange + Book</a>. One fairly often hears references to "C2 security" or a + product "evaluated at B1". The Rainbow books define the standards + referred to in those comments. + <p>See this <a href="http://www.fas.org/irp/nsa/rainbow.htm">reference + page</a>.</p> + <p>The Rainbow books are now mainly obsolete, replaced by the + international <a href="#cc">Common Criteria</a> standards.</p> + </dd> + <dt><a name="random">Random</a></dt> + <dd>A remarkably tricky term, far too much so for me to attempt a + definition here. Quite a few cryptosystems have been broken via attacks + on weak random number generators, even when the rest of the system was + sound. + <p>See <a + href="http://nis.nsf.net/internet/documents/rfc/rfc1750.txt">RFC + 1750</a> for the theory.</p> + <p>See the manual pages for <a + href="manpage.d/ipsec_ranbits.8.html">ipsec_ranbits(8)</a> and + ipsec_prng(3) for more on FreeS/WAN's use of randomness. Both depend on + the random(4) device driver..</p> + <p>A couple of years ago, there was extensive mailing list discussion + (archived <a + href="http://www.openpgp.net/random/index.html">here</a>)of Linux + /dev/random and FreeS/WAN. Since then, the design of the random(4) + driver has changed considerably. Linux 2.4 kernels have the new + driver..</p> + </dd> + <dt>Raptor</dt> + <dd>A firewall product for Windows NT offerring IPsec-based VPN services. + Linux FreeS/WAN interoperates with Raptor; see our <a + href="interop.html#Raptor">interop</a> document for details. Raptor + have recently merged with Axent.</dd> + <dt><a name="RC4">RC4</a></dt> + <dd><b>R</b>ivest <b>C</b>ipher four, designed by Ron Rivest of <a + href="#RSAco">RSA</a> and widely used. Believed highly secure with + adequate key length, but often implemented with inadequate key length + to comply with export restrictions.</dd> + <dt><a name="RC6">RC6</a></dt> + <dd><b>R</b>ivest <b>C</b>ipher six, <a href="#RSAco">RSA</a>'s <a + href="#AES">AES</a> candidate cipher.</dd> + <dt><a name="replay">Replay attack</a></dt> + <dd>An attack in which the attacker records data and later replays it in + an attempt to deceive the recipient.</dd> + <dt><a name="reverse">Reverse map</a></dt> + <dd>In <a href="#DNS">DNS</a>, a table where IP addresses can be used as + the key for lookups which return a system name and/or other + information.</dd> + <dt>RFC</dt> + <dd><b>R</b>equest <b>F</b>or <b>C</b>omments, an Internet document. Some + RFCs are just informative. Others are standards. + <p>Our list of <a href="#IPSEC">IPsec</a> and other security-related + RFCs is <a href="rfc.html#RFC">here</a>, along with information on + methods of obtaining them.</p> + </dd> + <dt><a name="rijndael">Rijndael</a></dt> + <dd>a <a href="#block">block cipher</a> designed by two Belgian + cryptographers, winner of the US government's <a href="#AES">AES</a> + contest to pick a replacement for <a href="#DES">DES</a>. See the <a + href="http://www.esat.kuleuven.ac.be/~rijmen/rijndael">Rijndael home + page</a>.</dd> + <dt><a name="RIPEMD">RIPEMD</a></dt> + <dd>A <a href="#digest">message digest</a> algorithm. The current version + is RIPEMD-160 which gives a 160-bit hash.</dd> + <dt><a name="rootCA">Root CA</a></dt> + <dd>The top level <a href="#CA">Certification Authority</a> in a hierachy + of such authorities.</dd> + <dt><a name="routable">Routable IP address</a></dt> + <dd>Most IP addresses can be used as "to" and "from" addresses in packet + headers. These are the routable addresses; we expect routing to be + possible for them. If we send a packet to one of them, we expect (in + most cases; there are various complications) that it will be delivered + if the address is in use and will cause an <a + href="#ICMP.gloss">ICMP</a> error packet to come back to us if not. + <p>There are also several classes of <a + href="#non-routable">non-routable</a> IP addresses.</p> + </dd> + <dt><a name="RSA">RSA algorithm</a></dt> + <dd><b>R</b>ivest <b>S</b>hamir <b>A</b>dleman <a href="#public">public + key</a> algorithm, named for its three inventors. It is widely used and + likely to become moreso since it became free of patent encumbrances in + September 2000. + <p>RSA can be used to provide either <a + href="#encryption">encryption</a> or <a href="#signature">digital + signatures</a>. In IPsec, it is used only for signatures. These provide + gateway-to-gateway <a href="#authentication">authentication</a> for <a + href="#IKE">IKE </a>negotiations.</p> + <p>For a full explanation of the algorithm, consult one of the standard + references such as <a href="biblio.html#schneier">Applied + Cryptography</a>. A simple explanation is:</p> + <p>The great 17th century French mathematician <a + href="http://www-groups.dcs.st-andrews.ac.uk/~history/Mathematicians/Fermat.html">Fermat</a> + proved that,</p> + <p>for any prime p and number x, 0 <= x < p:</p> + <pre> x^p == x modulo p + x^(p-1) == 1 modulo p, non-zero x + </pre> + <p>From this it follows that if we have a pair of primes p, q and two + numbers e, d such that:</p> + <pre> ed == 1 modulo lcm( p-1, q-1) + </pre> + where lcm() is least common multiple, then<br> + for all x, 0 <= x < pq: + <pre> x^ed == x modulo pq + </pre> + <p>So we construct such as set of numbers p, q, e, d and publish the + product N=pq and e as the public key. Using c for <a + href="#ciphertext">ciphertext</a> and i for the input <a + href="#plaintext">plaintext</a>, encryption is then:</p> + <pre> c = i^e modulo N + </pre> + <p>An attacker cannot deduce i from the cyphertext c, short of either + factoring N or solving the <a href="#dlog">discrete logarithm</a> + problem for this field. If p, q are large primes (hundreds or thousands + of bits) no efficient solution to either problem is known.</p> + <p>The receiver, knowing the private key (N and d), can readily recover + the plaintext p since:</p> + <pre> c^d == (i^e)^d modulo N + == i^ed modulo N + == i modulo N + </pre> + <p>This gives an effective public key technique, with only a couple of + problems. It uses a good deal of computer time, since calculations with + large integers are not cheap, and there is no proof it is necessarily + secure since no-one has proven either factoring or discrete log cannot + be done efficiently. Quite a few good mathematicians have tried both + problems, and no-one has announced success, but there is no proof they + are insoluble.</p> + </dd> + <dt><a name="RSAco">RSA Data Security</a></dt> + <dd>A company founded by the inventors of the <a href="#RSA">RSA</a> + public key algorithm.</dd> + <dt><a name="S">S</a></dt> + <dt><a name="SA">SA</a></dt> + <dd><b>S</b>ecurity <b>A</b>ssociation, the channel negotiated by the + higher levels of an <a href="#IPSEC">IPsec</a> implementation (<a + href="#IKE">IKE</a>) and used by the lower (<a href="#ESP">ESP</a> and + <a href="#AH">AH</a>). SAs are unidirectional; you need a pair of them + for two-way communication. + <p>An SA is defined by three things -- the destination, the protocol + (<a href="#AH">AH</a> or<a href="#ESP">ESP</a>) and the <a + href="SPI">SPI</a>, security parameters index. It is used as an index + to look up other things such as session keys and intialisation + vectors.</p> + <p>For more detail, see our section on <a href="ipsec.html">IPsec</a> + and/or RFC 2401.</p> + </dd> + <dt><a name="SElinux">SE Linux</a></dt> + <dd><strong>S</strong>ecurity <strong>E</strong>nhanced Linux, an <a + href="#NSA">NSA</a>-funded project to add <a + href="#mandatory">mandatory access control</a> to Linux. See the <a + href="http://www.nsa.gov/selinux">project home page</a>. + <p>According to their web pages, this work will include extending + mandatory access controls to IPsec tunnels.</p> + <p>Recent versions of SE Linux code use the <a href="#LSM">Linux + Security Module</a> interface.</p> + </dd> + <dt><a name="SDNS">Secure DNS</a></dt> + <dd>A version of the <a href="#DNS">DNS or Domain Name Service</a> + enhanced with authentication services. This is being designed by the <a + href="#IETF">IETF</a> DNS security <a + href="http://www.ietf.org/ids.by.wg/dnssec.html">working group</a>. + Check the <a href="http://www.isc.org/bind.html">Internet Software + Consortium</a> for information on implementation progress and for the + latest version of <a href="#BIND">BIND</a>. Another site has <a + href="http://www.toad.com/~dnssec">more information</a>. + <p><a href="#IPSEC">IPsec</a> can use this plus <a + href="#DH">Diffie-Hellman key exchange</a> to bootstrap itself. This + allows <a href="#carpediem">opportunistic encryption</a>. Any pair of + machines which can authenticate each other via DNS can communicate + securely, without either a pre-existing shared secret or a shared <a + href="#PKI">PKI</a>.</p> + </dd> + <dt>Secret key cryptography</dt> + <dd>See <a href="#symmetric">symmetric cryptography</a></dd> + <dt>Security Association</dt> + <dd>see <a href="#SA">SA</a></dd> + <dt>Security Enhanced Linux</dt> + <dd>see <a href="#SElinux">SE Linux</a></dd> + <dt><a name="sequence">Sequence number</a></dt> + <dd>A number added to a packet or message which indicates its position in + a sequence of packets or messages. This provides some security against + <a href="#replay">replay attacks</a>. + <p>For <a href="#auto">automatic keying</a> mode, the <a + href="#IPSEC">IPsec</a> RFCs require that the sender generate sequence + numbers for each packet, but leave it optional whether the receiver + does anything with them.</p> + </dd> + <dt><a name="SHA">SHA</a></dt> + <dt>SHA-1</dt> + <dd><b>S</b>ecure <b>H</b>ash <b>A</b>lgorithm, a <a + href="#digest">message digest algorithm</a> developed by the <a + href="#NSA">NSA</a> for use in the Digital Signature standard, <a + href="#FIPS">FIPS</a> number 186 from <a href="#NIST">NIST</a>. SHA is + an improved variant of <a href="#MD4">MD4</a> producing a 160-bit hash. + <p>SHA is one of two message digest algorithms available in IPsec. The + other is <a href="#MD5">MD5</a>. Some people do not trust SHA because + it was developed by the <a href="#NSA">NSA</a>. There is, as far as we + know, no cryptographic evidence that SHA is untrustworthy, but this + does not prevent that view from being strongly held.</p> + <p>The NSA made one small change after the release of the original SHA. + They did not give reasons. Iit may be a defense against some attack + they found and do not wish to disclose. Technically the modified + algorithm should be called SHA-1, but since it has replaced the + original algorithm in nearly all applications, it is generally just + referred to as SHA..</p> + </dd> + <dt><a name="SHA-256">SHA-256</a></dt> + <dt>SHA-384</dt> + <dt>SHA-512</dt> + <dd>Newer variants of SHA designed to match the strength of the 128, 192 + and 256-bit keys of <a href="#AES">AES</a>. The work to break an + encryption algorithm's strength by <a href="#brute">brute force</a> is + 2 + <math xmlns="http://www.w3.org/1998/Math/MathML"> + <msup> + <mi>keylength</mi> + </msup> + </math> + operations but a <a href="birthday">birthday attack </a>on a hash + needs only 2 + <math xmlns="http://www.w3.org/1998/Math/MathML"> + <msup> + <mrow> + <mi>hashlength</mi> + <mo>/</mo> + <mn>2</mn> + </mrow> + </msup> + </math> + , so as a general rule you need a hash twice the size of the key to + get similar strength. SHA-256, SHA-384 and SHA-512 are designed to + match the 128, 192 and 256-bit key sizes of AES, respectively.</dd> + <dt><a name="SIGINT">Signals intelligence (SIGINT)</a></dt> + <dd>Activities of government agencies from various nations aimed at + protecting their own communications and reading those of others. + Cryptography, cryptanalysis, wiretapping, interception and monitoring + of various sorts of signals. The players include the American <a + href="#NSA">NSA</a>, British <a href="#GCHQ">GCHQ</a> and Canadian <a + href="#CSE">CSE</a>.</dd> + <dt><a name="SKIP">SKIP</a></dt> + <dd><b>S</b>imple <b>K</b>ey management for <b>I</b>nternet + <b>P</b>rotocols, an alternative to <a href="#IKE">IKE</a> developed by + Sun and being marketed by their <a + href="http://skip.incog.com">Internet Commerce Group</a>.</dd> + <dt><a name="snake">Snake oil</a></dt> + <dd>Bogus cryptography. See the <a + href="http://www.interhack.net/people/cmcurtin/snake-oil-faq.html"> + Snake Oil FAQ</a> or <a + href="http://www.counterpane.com/crypto-gram-9902.html#snakeoil">this + paper</a> by Schneier.</dd> + <dt><a name="SPI">SPI</a></dt> + <dd><b>S</b>ecurity <b>P</b>arameter <b>I</b>ndex, an index used within + <a href="#IPSEC">IPsec</a> to keep connections distinct. A <a + href="#SA">Security Association (SA)</a> is defined by destination, + protocol and SPI. Without the SPI, two connections to the same gateway + using the same protocol could not be distinguished. + <p>For more detail, see our <a href="ipsec.html">IPsec</a> section + and/or RFC 2401.</p> + </dd> + <dt><a name="SSH">SSH</a></dt> + <dd><b>S</b>ecure <b>SH</b>ell, an encrypting replacement for the + insecure Berkeley commands whose names begin with "r" for "remote": + rsh, rlogin, etc. + <p>For more information on SSH, including how to obtain it, see our + cryptography <a href="web.html#tools">links</a>.</p> + </dd> + <dt><a name="SSHco">SSH Communications Security</a></dt> + <dd>A company founded by the authors of <a href="#SSH">SSH</a>. Offices + are in <a href="http://www.ssh.fi">Finland</a> and <a + href="http://www.ipsec.com">California</a>. They have a toolkit for + developers of IPsec applications.</dd> + <dt><a name="SSL">SSL</a></dt> + <dd><a href="http://home.netscape.com/eng/ssl3">Secure Sockets Layer</a>, + a set of encryption and authentication services for web browsers, + developed by Netscape. Widely used in Internet commerce. Also known as + <a href="#TLS">TLS</a>.</dd> + <dt>SSLeay</dt> + <dd>A free implementation of <a href="#SSL">SSL</a> by Eric Young (eay) + and others. Developed in Australia; not subject to US export + controls.</dd> + <dt><a name="static">static IP address</a></dt> + <dd>an IP adddress which is pre-set on the machine itself, as opposed to + a <a href="#dynamic">dynamic address</a> which is assigned by a <a + href="#DHCP">DHCP</a> server or obtained as part of the process of + establishing a <a href="#PPP">PPP</a> or <a href="#PPPoE">PPPoE</a> + connection</dd> + <dt><a name="stream">Stream cipher</a></dt> + <dd>A <a href="#symmetric">symmetric cipher</a> which produces a stream + of output which can be combined (often using XOR or bytewise addition) + with the plaintext to produce ciphertext. Contrasts with <a + href="#block">block cipher</a>. + <p><a href="#IPSEC">IPsec</a> does not use stream ciphers. Their main + application is link-level encryption, for example of voice, video or + data streams on a wire or a radio signal.</p> + </dd> + <dt><a name="subnet">subnet</a></dt> + <dd>A group of IP addresses which are logically one network, typically + (but not always) assigned to a group of physically connected machines. + The range of addresses in a subnet is described using a subnet mask. + See next entry.</dd> + <dt>subnet mask</dt> + <dd>A method of indicating the addresses included in a subnet. Here are + two equivalent examples: + <ul> + <li>101.101.101.0/24</li> + <li>101.101.101.0 with mask 255.255.255.0</li> + </ul> + <p>The '24' is shorthand for a mask with the top 24 bits one and the + rest zero. This is exactly the same as 255.255.255.0 which has three + all-ones bytes and one all-zeros byte.</p> + <p>These indicate that, for this range of addresses, the top 24 bits + are to be treated as naming a network (often referred to as "the + 101.101.101.0/24 subnet") while most combinations of the low 8 bits can + be used to designate machines on that network. Two addresses are + reserved; 101.101.101.0 refers to the subnet rather than a specific + machine while 101.101.101.255 is a broadcast address. 1 to 254 are + available for machines.</p> + <p>It is common to find subnets arranged in a hierarchy. For example, a + large company might have a /16 subnet and allocate /24 subnets within + that to departments. An ISP might have a large subnet and allocate /26 + subnets (64 addresses, 62 usable) to business customers and /29 subnets + (8 addresses, 6 usable) to residential clients.</p> + </dd> + <dt><a name="SWAN">S/WAN</a></dt> + <dd>Secure Wide Area Network, a project involving <a href="#RSAco">RSA + Data Security</a> and a number of other companies. The goal was to + ensure that all their <a href="#IPSEC">IPsec</a> implementations would + interoperate so that their customers can communicate with each other + securely.</dd> + <dt><a name="symmetric">Symmetric cryptography</a></dt> + <dd>Symmetric cryptography, also referred to as conventional or secret + key cryptography, relies on a <em>shared secret key</em>, identical for + sender and receiver. Sender encrypts with that key, receiver decrypts + with it. The idea is that an eavesdropper without the key be unable to + read the messages. There are two main types of symmetric cipher, <a + href="#block">block ciphers</a> and <a href="#stream">stream + ciphers</a>. + <p>Symmetric cryptography contrasts with <a href="#public">public + key</a> or asymmetric systems where the two players use different + keys.</p> + <p>The great difficulty in symmetric cryptography is, of course, key + management. Sender and receiver <em>must</em> have identical keys and + those keys <em>must</em> be kept secret from everyone else. Not too + much of a problem if only two people are involved and they can + conveniently meet privately or employ a trusted courier. Quite a + problem, though, in other circumstances.</p> + <p>It gets much worse if there are many people. An application might be + written to use only one key for communication among 100 people, for + example, but there would be serious problems. Do you actually trust all + of them that much? Do they trust each other that much? Should they? + What is at risk if that key is compromised? How are you going to + distribute that key to everyone without risking its secrecy? What do + you do when one of them leaves the company? Will you even know?</p> + <p>On the other hand, if you need unique keys for every possible + connection between a group of 100, then each user must have 99 keys. + You need either 99*100/2 = 4950 <em>secure</em> key exchanges between + users or a central authority that <em>securely</em> distributes 100 key + packets, each with a different set of 99 keys.</p> + <p>Either of these is possible, though tricky, for 100 users. Either + becomes an administrative nightmare for larger numbers. Moreover, keys + <em>must</em> be changed regularly, so the problem of key distribution + comes up again and again. If you use the same key for many messages + then an attacker has more text to work with in an attempt to crack that + key. Moreover, one successful crack will give him or her the text of + all those messages.</p> + <p>In short, the <em>hardest part of conventional cryptography is key + management</em>. Today the standard solution is to build a <a + href="#hybrid">hybrid system</a> using <a href="#public">public key</a> + techniques to manage keys.</p> + </dd> + <dt><a name="T">T</a></dt> + <dt><a name="TIS">TIS</a></dt> + <dd>Trusted Information Systems, a firewall vendor now part of <a + href="#NAI">NAI</a>. Their Gauntlet product offers IPsec VPN services. + TIS implemented the first version of <a href="#SDNS">Secure DNS</a> on + a <a href="#DARPA">DARPA</a> contract.</dd> + <dt><a name="TLS">TLS</a></dt> + <dd><b>T</b>ransport <b>L</b>ayer <b>S</b>ecurity, a newer name for <a + href="#SSL">SSL</a>.</dd> + <dt><a name="TOS">TOS field</a></dt> + <dd>The <strong>T</strong>ype <strong>O</strong>f + <strong>S</strong>ervice field in an IP header, used to control + qualkity of service routing.</dd> + <dt><a name="traffic">Traffic analysis</a></dt> + <dd>Deducing useful intelligence from patterns of message traffic, + without breaking codes or reading the messages. In one case during + World War II, the British guessed an attack was coming because all + German radio traffic stopped. The "radio silence" order, intended to + preserve security, actually gave the game away. + <p>In an industrial espionage situation, one might deduce something + interesting just by knowing that company A and company B were talking, + especially if one were able to tell which departments were involved, or + if one already knew that A was looking for acquisitions and B was + seeking funds for expansion.</p> + <p>In general, traffic analysis by itself is not very useful. However, + in the context of a larger intelligence effort where quite a bit is + already known, it can be very useful. When you are solving a complex + puzzle, every little bit helps.</p> + <p><a href="#IPSEC">IPsec</a> itself does not defend against traffic + analysis, but carefully thought out systems using IPsec can provide at + least partial protection. In particular, one might want to encrypt more + traffic than was strictly necessary, route things in odd ways, or even + encrypt dummy packets, to confuse the analyst. We discuss this <a + href="ipsec.html#traffic.resist">here</a>.</p> + </dd> + <dt><a name="transport">Transport mode</a></dt> + <dd>An IPsec application in which the IPsec gateway is the destination of + the protected packets, a machine acts as its own gateway. Contrast with + <a href="#tunnel">tunnel mode</a>.</dd> + <dt>Triple DES</dt> + <dd>see <a href="#3DES">3DES</a></dd> + <dt><a name="TTL">TTL</a></dt> + <dd><strong>T</strong>ime <strong>T</strong>o <strong>L</strong>ive, used + to control <a href="#DNS">DNS</a> caching. Servers discard cached + records whose TTL expires</dd> + <dt><a name="tunnel">Tunnel mode</a></dt> + <dd>An IPsec application in which an IPsec gateway provides protection + for packets to and from other systems. Contrast with <a + href="#transport">transport mode</a>.</dd> + <dt><a name="2key">Two-key Triple DES</a></dt> + <dd>A variant of <a href="#3DES">triple DES or 3DES</a> in which only two + keys are used. As in the three-key version, the order of operations is + <a href="#EDE">EDE</a> or encrypt-decrypt-encrypt, but in the two-key + variant the first and third keys are the same. + <p>3DES with three keys has 3*56 = 168 bits of key but has only 112-bit + strength against a <a href="#meet">meet-in-the-middle</a> attack, so it + is possible that the two key version is just as strong. Last I looked, + this was an open question in the research literature.</p> + <p>RFC 2451 defines triple DES for <a href="#IPSEC">IPsec</a> as the + three-key variant. The two-key variant should not be used and is not + implemented directly in <a href="#FreeSWAN">Linux FreeS/WAN</a>. It + cannot be used in automatically keyed mode without major fiddles in the + source code. For manually keyed connections, you could make Linux + FreeS/WAN talk to a two-key implementation by setting two keys the same + in /etc/ipsec.conf.</p> + </dd> + <dt><a name="U">U</a></dt> + <dt><a name="V">V</a></dt> + <dt><a name="virtual">Virtual Interface</a></dt> + <dd>A <a href="#Linux">Linux</a> feature which allows one physical + network interface to have two or more IP addresses. See the <cite>Linux + Network Administrator's Guide</cite> in <a + href="biblio.html#kirch">book form</a> or <a + href="http://metalab.unc.edu/LDP/LDP/nag/node1.html">on the web</a> for + details.</dd> + <dt>Virtual Private Network</dt> + <dd>see <a href="#VPN">VPN</a></dd> + <dt><a name="VPN">VPN</a></dt> + <dd><b>V</b>irtual <b>P</b>rivate <b>N</b>etwork, a network which can + safely be used as if it were private, even though some of its + communication uses insecure connections. All traffic on those + connections is encrypted. + <p><a href="#IPSEC">IPsec</a> is not the only technique available for + building VPNs, but it is the only method defined by <a + href="#RFC">RFCs</a> and supported by many vendors. VPNs are by no + means the only thing you can do with IPsec, but they may be the most + important application for many users.</p> + </dd> + <dt><a name="VPNC">VPNC</a></dt> + <dd><a href="http://www.vpnc.org">Virtual Private Network Consortium</a>, + an association of vendors of VPN products.</dd> + <dt><a name="W">W</a></dt> + <dt><a name="Wassenaar.gloss">Wassenaar Arrangement</a></dt> + <dd>An international agreement restricting export of munitions and other + tools of war. Unfortunately, cryptographic software is also restricted + under the current version of the agreement. <a + href="politics.html#Wassenaar">Discussion</a>.</dd> + <dt><a name="web">Web of Trust</a></dt> + <dd><a href="#PGP">PGP</a>'s method of certifying keys. Any user can sign + a key; you decide which signatures or combinations of signatures to + accept as certification. This contrasts with the hierarchy of <a + href="#CA">CAs (Certification Authorities)</a> used in many <a + href="#PKI">PKIs (Public Key Infrastructures)</a>. + <p>See <a href="#GTR">Global Trust Register</a> for an interesting + addition to the web of trust.</p> + </dd> + <dt><a name="WEP">WEP (Wired Equivalent Privacy)</a></dt> + <dd>The cryptographic part of the <a href="#IEEE">IEEE</a> standard for + wireless LANs. As the name suggests, this is designed to be only as + secure as a normal wired ethernet. Anyone with a network conection can + tap it. Its advocates would claim this is good design, refusing to + build in complex features beyond the actual requirements. + <p>Critics refer to WEP as "Wire<em>tap</em> Equivalent Privacy", and + consider it a horribly flawed design based on bogus "requirements". You + do not control radio waves as you might control your wires, so the + metaphor in the rationale is utterly inapplicable. A security policy + that chooses not to invest resources in protecting against certain + attacks which can only be conducted by people physically plugged into + your LAN may or may not be reasonable. The same policy is completely + unreasonable when someone can "plug in" from a laptop half a block + away..</p> + <p>There has been considerable analysis indicating that WEP is + seriously flawed. A FAQ on attacks against WEP is available. Part of it + reads:</p> + + <blockquote> + ... attacks are practical to mount using only inexpensive + off-the-shelf equipment. We recommend that anyone using an 802.11 + wireless network not rely on WEP for security, and employ other + security measures to protect their wireless network. Note that our + attacks apply to both 40-bit and the so-called 128-bit versions of + WEP equally well.</blockquote> + <p>WEP appears to be yet another instance of governments, and + unfortunately some vendors and standards bodies, deliberately promoting + hopelessly flawed "security" products, apparently mainly for the + benefit of eavesdropping agencies. See this <a + href="politics.html#weak">discussion</a>.</p> + </dd> + <dt><a name="X">X</a></dt> + <dt><a name="X509">X.509</a></dt> + <dd>A standard from the <a href="http://www.itu.int">ITU (International + Telecommunication Union)</a>, for hierarchical directories with + authentication services, used in many <a href="#PKI">PKI</a> + implementations. + <p>Use of X.509 services, via the <a href="#LDAP">LDAP protocol</a>, + for certification of keys is allowed but not required by the <a + href="#IPSEC">IPsec</a> RFCs. It is not yet implemented in <a + href="#FreeSWAN">Linux FreeS/WAN</a>.</p> + </dd> + <dt>Xedia</dt> + <dd>A vendor of router and Internet access products, now part of Lucent. + Their QVPN products interoperate with Linux FreeS/WAN; see our <a + href="interop.html#Xedia">interop document</a>.</dd> + <dt><a name="Y">Y</a></dt> + <dt><a name="Z">Z</a></dt> +</dl> +</body> +</html> diff --git a/doc/src/index.html b/doc/src/index.html new file mode 100644 index 000000000..e2530d711 --- /dev/null +++ b/doc/src/index.html @@ -0,0 +1,55 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN index</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, encryption, cryptography, FreeS/WAN, FreeSWAN"> + <!-- + + Written by Claudia Schmeing for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: index.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1>FreeS/WAN documentation</h1> + +<ul> + <li><a href="intro.html">Introduction</a></li> + <li><a href="upgrading.html">Upgrading to 2.x</a></li> +</ul> + +<ul> + <li><a href="quickstart.html">Quickstart guide to Opportunistic Encryption</a></li> + <li><a href="install.html">Installing</a></li> + <li><a href="config.html">Configuring</a></li> + <li><a href="policygroups.html">Policy Groups</a> + </li> + <li><a href="interop.html">Interoperating</a> +<FONT COLOR="#FF0000">New and improved!</FONT></li> + <li><a href="faq.html">FAQ</a></li> + <li><a href="trouble.html">Troubleshooting and problem reporting</a></li> +</ul> + +<ul> + <li><a href="toc.html">Full table of contents, with much more</a></li> + <li><a href="HowTo.html">All our docs as one big file</a></li> +</ul> + +<p>For technical support and other questions, use our <a +href="mail.html">mailing lists</a>.</p> + +<pre> This index last changed: $Date: 2004/03/15 20:35:24 $</pre> + +</body> +</html> diff --git a/doc/src/initiatorstate.txt b/doc/src/initiatorstate.txt new file mode 100644 index 000000000..315f6da4c --- /dev/null +++ b/doc/src/initiatorstate.txt @@ -0,0 +1,66 @@ + + | + | PF_ACQUIRE + | + V + .---------------. + | non-existant | + | connection | + `---------------' + | | | + send , | \ +expired pass / | \ send +conn. msg / | \ deny + ^ / | \ msg + | V | do \ +.---------------. | DNS \ .---------------. +| clear-text | | lookup `->| deny |---> expired +| connection | | for | connection | connection +`---------------' | destination `---------------' + ^ ^ | ^ + | | no record | | + | | OE-permissive V | no record + | | .---------------. | OE-paranoid + | `------------| potential OE |---------' + | | connection | ^ + | `---------------' | + | | | + | | got TXT record | DNSSEC failure + | | reply | + | V | wrong + | .---------------. | failure + | | authenticate |---------' + | | & parse TXT RR| ^ + | repeated `---------------' | + | ICMP | | + | failures | initiate IKE to | + | (short-timeout) | responder | + | V | + | phase-2 .---------------. | failure + | failure | pending |---------' + | (normal | OE | ^ + | timeout) | |invalid | phase-2 failure (short-timeout) + | | |<--.SPI | ICMP failures (normal timeout) + | | | | | + | | +=======+ |---' | + | | | IKE | | ^ | + `--------------| | states|---------------' + | +=======+ | | + `---------------' | + | | invalid SPI + | | + V | rekey time + .--------------. | + | keyed |<---|-------------------------------. + | connection |----' | + `--------------' | + | | + | | + V | + .--------------. connection still active | + clear-text----->| expired |------------------------------------' + deny----->| connection | + `--------------' + + +$Id: initiatorstate.txt,v 1.1 2004/03/15 20:35:24 as Exp $ diff --git a/doc/src/install.html b/doc/src/install.html new file mode 100644 index 000000000..09d7c5a67 --- /dev/null +++ b/doc/src/install.html @@ -0,0 +1,378 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>Installing FreeS/WAN</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, installation, quickstart"> + <!-- + + Written by Claudia Schmeing for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: install.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> +<BODY> +<H1><A name="install">Installing FreeS/WAN</A></H1> + +<P>This document will teach you how to install Linux FreeS/WAN. +If your distribution comes with Linux FreeS/WAN, we offer + tips to get you started.</P> + +<H2>Requirements</H2> + +<P>To install FreeS/WAN you must:</P> +<UL> +<LI>be running Linux with the 2.4 or 2.2 kernel series. See +this <A HREF="http://www.freeswan.ca/download.php#contact">kernel +compatibility table</A>.<BR>We also have experimental support for +2.6 kernels. Here are two basic approaches: +<UL><LI> +install FreeS/WAN, including its <A HREF="ipsec.html#parts">KLIPS</A> +kernel code. This will remove the native IPsec stack and replace it +with KLIPS.</LI> +<LI> +install the FreeS/WAN <A HREF="ipsec.html#parts">userland tools</A> +(keying daemon and supporting +scripts) for use with +<A HREF="http://lartc.org/howto/lartc.ipsec.html">2.6 kernel native IPsec</A>, +</LI> +</UL> +See also these <A HREF="2.6.known-issues">known issues with 2.6</A>. +<LI>have root access to your Linux box</LI> +<LI>choose the version of FreeS/WAN you wish to install based on +<A HREF="http://www.freeswan.org/mail.html">mailing list reports</A> <!-- or +our updates page (coming soon)--></LI> +</UL> + +<H2>Choose your install method</H2> + +<P>There are three basic ways to get FreeS/WAN onto your system:</P> +<UL> +<LI>activating and testing a FreeS/WAN that <A HREF="#distroinstall">shipped +with your Linux distribution</A></LI> +<LI><A HREF="#rpminstall">RPM install</A></LI> +<LI><A HREF="#srcinstall">Install from source</A></LI> +</UL> + +<A NAME="distroinstall"></A><H2>FreeS/WAN ships with some Linuxes</H2> + +<P>FreeS/WAN comes with <A HREF="intro.html#distwith">these distributions</A>. + +<P>If you're running one of these, include FreeS/WAN in the choices you +make during installation, or add it later using the distribution's tools. +</P> + +<H3>FreeS/WAN may be altered...</H3> +<P>Your distribution may have integrated extra features, such as Andreas +Steffen's X.509 patch, into FreeS/WAN. It may also use custom +startup script locations or directory names.</P> + +<H3>You might need to create an authentication keypair</H3> + +<P>If your FreeS/WAN came with your distribution, you may wish to + generate a fresh RSA key pair. FreeS/WAN will use these keys + for authentication. + +<P> +To do this, become root, and type: +</P> + +<PRE> ipsec newhostkey --output /etc/ipsec.secrets --hostname xy.example.com + chmod 600 /etc/ipsec.secrets</PRE> + +<P>where you replace xy.example.com with your machine's fully-qualified +domain name. Generate some randomness, for example by wiggling your mouse, +to speed the process. +</P> + +<P>The resulting ipsec.secrets looks like:</P> +<PRE>: RSA { + # RSA 2192 bits xy.example.com Sun Jun 8 13:42:19 2003 + # for signatures only, UNSAFE FOR ENCRYPTION + #pubkey=0sAQOFppfeE3cC7wqJi... + Modulus: 0x85a697de137702ef0... + # everything after this point is secret + PrivateExponent: 0x16466ea5033e807... + Prime1: 0xdfb5003c8947b7cc88759065... + Prime2: 0x98f199b9149fde11ec956c814... + Exponent1: 0x9523557db0da7a885af90aee... + Exponent2: 0x65f6667b63153eb69db8f300dbb... + Coefficient: 0x90ad00415d3ca17bebff123413fc518... + } +# do not change the indenting of that "}"</PRE> + +<P>In the actual file, the strings are much longer.</P> + + +<H3>Start and test FreeS/WAN</H3> + +<P>You can now <A HREF="install.html#starttest">start FreeS/WAN and +test whether it's been successfully installed.</A>.</P> + + +<A NAME="rpminstall"></A><H2>RPM install</H2> + +<P>These instructions are for a recent Red Hat with a stock Red Hat kernel. +We know that Mandrake and SUSE also produce FreeS/WAN RPMs. If you're +running either, install using your distribution's tools.</P> + +<H3>Download RPMs</H3> + +<P>Decide which functionality you need:</P> +<UL> +<LI>standard FreeS/WAN RPMs. Use these shortcuts:<BR> +<UL> +<LI>(for 2.6 kernels: userland only)<BR> +ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/\*userland*</LI> + +<LI>(for 2.4 kernels)<BR> +ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/`uname -r | tr -d 'a-wy-z'`/\*</LI> +<LI> +or view all the offerings at our +<A href="ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs">FTP site</A>. +</LI></UL> +</LI> +<LI>unofficial +<A href="http://www.freeswan.ca/download.php">Super FreeS/WAN</A> +RPMs, which include Andreas Steffen's X.509 patch and more. +Super FreeS/WAN RPMs do not currently include +<A HREF="glossary.html#NAT.gloss">Network Address Translation</A> +(NAT) traversal, but Super FreeS/WAN source does.</LI> +</UL> + +<A NAME="2.6.rpm"></A> +<P>For 2.6 kernels, get the latest FreeS/WAN userland RPM, for example:</P> +<PRE> freeswan-userland-2.04.9-0.i386.rpm</PRE> + +<P>Note: FreeS/WAN's support for 2.6 kernel IPsec is preliminary. Please see +<A HREf="2.6.known-issues">2.6.known-issues</A>, and the latest +<A HREF="http://www.freeswan.org/mail.html">mailing list reports</A>.</P> +<P>Change to your new FreeS/WAN directory, and make and install the + +<P>For 2.4 kernels, get both kernel and userland RPMs. +Check your kernel version with</P> +<PRE> uname -r</PRE> + +<P>Get a kernel module which matches that version. For example:</P> +<PRE> freeswan-module-2.04_2.4.20_20.9-0.i386.rpm</PRE> +<P>Note: These modules +<B>will only work on the Red Hat kernel they were built for</B>, +since they are very sensitive to small changes in the kernel.</P> + + +<P>Get FreeS/WAN utilities to match. For example:</P> +<PRE> freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm</PRE> + + +<H3>For freeswan.org RPMs: check signatures</H3> + +<P>While you're at our ftp site, grab the RPM signing key</P> +<PRE> freeswan-rpmsign.asc</PRE> + +<P>If you're running RedHat 8.x or later, import this key into the RPM +database:</P> +<PRE> rpm --import freeswan-rpmsign.asc</PRE> + +<P>For RedHat 7.x systems, you'll need to add it to your +<A HREF="glossary.html#PGP">PGP</A> keyring:</P> +<PRE> pgp -ka freeswan-rpmsign.asc</PRE> + + +<P>Check the digital signatures on both RPMs using:</P> +<PRE> rpm --checksig freeswan*.rpm </PRE> + +<P>You should see that these signatures are good:</P> +<PRE> freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK + freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK</PRE> + + +<H3>Install the RPMs</H3> + +<P>Become root:</P> +<PRE> su</PRE> + +<P>For a first time install, use:</P> +<PRE> rpm -ivh freeswan*.rpm</PRE> + +<P>To upgrade existing RPMs (and keep all .conf files in place), use:</P> +<PRE> rpm -Uvh freeswan*.rpm</PRE> + +<P>If you're upgrading from FreeS/WAN 1.x to 2.x RPMs, and encounter problems, +see <A HREF="upgrading.html#upgrading.rpms">this note</A>.</P> + + +<H3>Start and Test FreeS/WAN</H3> + +<P>Now, <A HREF="install.html#starttest">start FreeS/WAN and test your +install</A>.</P> + + +<A NAME="srcinstall"></A><H2>Install from Source</H2> +<!-- Most of this section, along with "Start and Test", can replace +INSTALL. --> + +<H3>Decide what functionality you need</H3> + +<P>Your choices are:</P> +<UL> +<LI><A HREF="ftp://ftp.xs4all.nl/pub/crypto/freeswan">standard +FreeS/WAN</A>,</LI> +<LI>standard FreeS/WAN plus any of these + <A HREF="web.html#patch">user-supported patches</A>, or</LI> +<LI><A HREF="http://www.freeswan.ca/download">Super FreeS/WAN</A>, +an unofficial FreeS/WAN pre-patched with many of the above. Provides +additional algorithms, X.509, SA deletion, dead peer detection, and +<A HREF="glossary.html#NAT.gloss">Network Address Translation</A> +(NAT) traversal.</LI> +</UL> + +<H3>Download FreeS/WAN</H3> + +<P>Download the source tarball you've chosen, along with any patches.</P> + +<H3>For freeswan.org source: check its signature</H3> + +<P>While you're at our ftp site, get our source signing key</P> +<PRE> freeswan-sigkey.asc</PRE> + +<P>Add it to your PGP keyring:</P> +<PRE> pgp -ka freeswan-sigkey.asc</PRE> + + +<P>Check the signature using:</P> +<PRE> pgp freeswan-2.04.tar.gz.sig freeswan-2.04.tar.gz</PRE> +<P>You should see something like:</P> +<PRE> Good signature from user "Linux FreeS/WAN Software Team (build@freeswan.org)". + Signature made 2002/06/26 21:04 GMT using 2047-bit key, key ID 46EAFCE1</PRE> +<!-- Note to self: build@freeswan.org has angled brackets in the original. + Changed because it conflicts with HTML tags. --> + +<H3>Untar, unzip</H3> + +<P>As root, unpack your FreeS/WAN source into <VAR>/usr/src</VAR>.</P> +<PRE> su + mv freeswan-2.04.tar.gz /usr/src + cd /usr/src + tar -xzf freeswan-2.04.tar.gz +</PRE> + +<H3>Patch if desired</H3> + +<P>Now's the time to add any patches. The contributor may have special +instructions, or you may simply use the patch command.</P> + +<H3>... and Make</H3> + +<P>Choose one of the methods below.</P> + +<H4>Userland-only Install for 2.6 kernels</H4> +<A NAME="2.6.src"></A> + +<P>Note: FreeS/WAN's support for 2.6 kernel IPsec is preliminary. Please see +<A HREf="2.6.known-issues">2.6.known-issues</A>, and the latest +<A HREF="http://www.freeswan.org/mail.html">mailing list reports</A>.</P> +<P>Change to your new FreeS/WAN directory, and make and install the +FreeS/WAN userland tools.</P> +<PRE> cd /usr/src/freeswan-2.04 + make programs + make install</PRE> + +<P>Now, <A HREF="install.html#starttest">start FreeS/WAN and +test your install</A>.</P> + + + +<H4>KLIPS install for 2.2, 2.4, or 2.6 kernels</H4> + +<A NAME="modinstall"></A> + +<P>To make a modular version of KLIPS, along with other FreeS/WAN programs +you'll need, use the command sequence below. This will +change to your new FreeS/WAN directory, make the FreeS/WAN module (and other +stuff), and install it all.</P> +<PRE> cd /usr/src/freeswan-2.04 + make oldmod + make minstall</PRE> + +<P><A HREF="install.html#starttest">Start FreeS/WAN and +test your install</A>.</P> + + + +<P>To link KLIPS statically into your kernel (using your old kernel settings), +and install other FreeS/WAN components, do: +</P> +<PRE> cd /usr/src/freeswan-2.04 + make oldmod + make minstall</PRE> + + +<P>Reboot your system and <A HREF="install.html#testonly">test your +install</A>.</P> + +<P>For other ways to compile KLIPS, see our Makefile.</P> + + + +<A name="starttest"></A><H2>Start FreeS/WAN and test your install</H2> + +<P>Bring FreeS/WAN up with:</P> +<PRE> service ipsec start</PRE> + +<P>This is not necessary if you've rebooted.</P> + +<A name="testonly"></A><H2>Test your install</H2> + +<P>To check that you have a successful install, run:</P> +<PRE> ipsec verify</PRE> + +<P>You should see at least:</P> +<PRE> + Checking your system to see if IPsec got installed and started correctly + Version check and ipsec on-path [OK] + Checking for KLIPS support in kernel [OK] + Checking for RSA private key (/etc/ipsec.secrets) [OK] + Checking that pluto is running [OK] +</PRE> + +<P>If any of these first four checks fails, see our +<A href="trouble.html#install.check">troubleshooting guide</A>. +</P> + + +<H2>Making FreeS/WAN play well with others</H2> + +<P>There are at least a couple of things on your system that might +interfere with FreeS/WAN, and now's a good time to check these:</P> +<UL> + <LI>Firewalling. You need to allow UDP 500 through your firewall, plus + ESP (protocol 50) and AH (protocol 51). For more information, see our + updated firewalls document (coming soon). + </LI> + <LI>Network address translation. +Do not NAT the packets you will be tunneling.</LI> +</UL> + + +<H2>Configure for your needs</H2> + +<P>You'll need to configure FreeS/WAN for your local site. Have a look at our +<A HREF="quickstart.html">opportunism quickstart guide</A> to see if that +easy method is right for your needs. Or, see how to <A HREF="config.html"> +configure a network-to-network or Road Warrior style VPN</A>. +</P> + + + + +</BODY> +</HTML> diff --git a/doc/src/interop.html b/doc/src/interop.html new file mode 100644 index 000000000..dd4f8c577 --- /dev/null +++ b/doc/src/interop.html @@ -0,0 +1,1802 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN interoperation Grid</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, interoperation"> + <!-- + + Written by Claudia Schmeing for the Linux FreeS/WAN project + With notes from Sandy Harris. + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: interop.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<A NAME="interop"></A><H1>Interoperating with FreeS/WAN</H1> + + +<P>The FreeS/WAN project needs you! We rely on the user community to keep +up to date. Mail users@lists.freeswan.org with your +interop success stories.</P> + +<P><STRONG>Please note</STRONG>: Most of our interop examples feature +Linux FreeS/WAN 1.x config files. You can convert them to 2.x files fairly +easily with the patch in our +<A HREF="upgrading.html#ipsec.conf_v2">Upgrading Guide</A>. +</P> + +<H2>Interop at a Glance</H2> + + + +<TABLE BORDER="1"> + +<TR> +<TD> </TD> +<TD colspan="5">FreeS/WAN VPN</TD> +<TD>Road Warrior</TD> +<TD>OE</TD> +</TR> + +<TR> +<TD> </TD> +<TD>PSK</TD> +<TD>RSA Secret</TD> +<TD>X.509<BR><SMALL><A HREF="#interoprules">(requires patch)</A></SMALL></TD> +<TD>NAT-Traversal<BR><SMALL><A HREF="#interoprules">(requires patch)</A></SMALL></TD> +<TD>Manual<BR>Keying</TD> +<TD> </TD> +<TD> </TD> +</TR> + + +<TR><TD colspan="8">More Compatible</TD></TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#freeswan">FreeS/WAN</A> +<A NAME="freeswan.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#isakmpd">isakmpd (OpenBSD)</A> +<A NAME="isakmpd.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#cc0000">No </FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#kame">Kame (FreeBSD, +<BR>NetBSD, MacOSX) +<BR> <SMALL>aka racoon</SMALL></A> +<A NAME="kame.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#mcafee">McAfee VPN<BR><SMALL>was PGPNet</SMALL></A> +<A NAME="mcafee.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#microsoft">Microsoft <BR>Windows 2000/XP</A> +<A NAME="microsoft.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> +<TR> +<TD><A HREF="#ssh">SSH Sentinel</A> +<A NAME="ssh.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#safenet">Safenet SoftPK<BR>/SoftRemote</A> +<A NAME="safenet.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<TR><TD colspan="8">Other</TD></TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#6wind">6Wind</A> +<A NAME="6wind.top"> </A></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#alcatel">Alcatel Timestep</A> +<A NAME="alcatel.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#apple">Apple Macintosh<br>System 10+</A> +<A NAME="apple.top"> </A></TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#ashleylaurent">AshleyLaurent <BR>VPCom</A> +<A NAME="ashleylaurent.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#borderware">Borderware</A> +<A NAME="borderware.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + +<!-- +http://www.cequrux.com/vpn-guides.php3 +"coming soon" guide to connect with FreeS/WAN. +--> + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#checkpoint">Check Point FW-1/VPN-1</A> +<A NAME="checkpoint.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#cisco">Cisco with 3DES</A> +<A NAME="cisco.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#equinux">Equinux VPN Tracker <BR> +(for Mac OS X) +</A> +<A NAME="equinux.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#fsecure">F-Secure</A> +<A NAME="fsecure.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#gauntlet">Gauntlet GVPN</A> +<A NAME="gauntlet.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#aix">IBM AIX</A> +<A NAME="aix.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#as400">IBM AS/400</A> +<A NAME="as400"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#intel">Intel Shiva<BR>LANRover/Net Structure</A> +<A NAME="intel.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#lancom">LanCom (formerly ELSA)</A> +<A NAME="lancom.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#linksys">Linksys</A> +<A NAME="linksys.top"> </A></TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#lucent">Lucent</A> +<A NAME="lucent.top"> </A></TD> +<TD><FONT color="#cccc00">Partial</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#netasq">Netasq</A> +<A NAME="netasq.top"> </A></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#netcelo">netcelo</A> +<A NAME="netcelo.top"> </A></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#netgear">Netgear fvs318</A> +<A NAME="netgear.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#netscreen">Netscreen 100<BR>or 5xp</A> +<A NAME="netscreen.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#nortel">Nortel Contivity</A> +<A NAME="nortel.top"> </A></TD> +<TD><FONT color="#cccc00">Partial</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#radguard">RadGuard</A> +<A NAME="radguard.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#raptor">Raptor</A> +<A NAME="raptor"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#redcreek">Redcreek Ravlin</A> +<A NAME="redcreek.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT><FONT color="#cccc00">/Partial</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#sonicwall">SonicWall</A> +<A NAME="sonicwall.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#sun">Sun Solaris</A> +<A NAME="sun.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#symantec">Symantec</A> +<A NAME="symantec.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#watchguard">Watchguard <BR>Firebox</A> +<A NAME="watchguard.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#xedia">Xedia Access Point<BR>/QVPN</A> +<A NAME="xedia.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +<TR> +<TD><A HREF="#zyxel">Zyxel Zywall<BR>/Prestige</A> +<A NAME="zyxel.top"> </A></TD> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE + + +<TR> +<TD><A HREF="#sample">sample</A></TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD> </TD> +<TD><FONT color="#cc0000">No</FONT></TD> +</TR> + +--> + +<TR> +<TD> </TD> +<TD>PSK</TD> +<TD>RSA Secret</TD> +<TD>X.509<BR><SMALL><A HREF="#interoprules">(requires patch)</A></SMALL></TD> +<TD>NAT-Traversal<BR><SMALL><A HREF="#interoprules">(requires patch)</A></SMALL></TD> +<TD>Manual<BR>Keying</TD> +<TD> </TD> +<TD> </TD> +</TR> + +<TR> +<TD> </TD> +<TD colspan="5">FreeS/WAN VPN</TD> +<TD>Road Warrior</TD> +<TD>OE</TD> +</TR> + + + +<!-- PSK RSA X.509 NAT-T Manual RW OE --> + +</TABLE> + + + + +<H3>Key</H3> +<TABLE BORDER="1"> + +<TR> +<TD><FONT color="#00cc00">Yes</FONT></TD> +<TD>People report that this works for them.</TD> +</TR> + +<TR> +<TD>[Blank]</TD> +<TD>We don't know.</TD> +</TR> + +<TR> +<TD><FONT color="#cc0000">No</FONT></TD> +<TD>We have reason to believe +it was, at some point, not possible to get this to work.</TD> +</TR> + +<TR> +<TD><FONT color="#cccc00">Partial</FONT></TD> +<TD>Partial success. For example, a connection can be +created from one end only.</TD> +</TR> + +<TR> +<TD><FONT color="#00cc00">Yes</FONT><FONT color="#cccc00">/Partial</FONT></TD> +<TD>Mixed reports.</TD> +</TR> + + +<TR> +<TD><FONT color="#cccc00">Maybe</FONT></TD> +<TD>We think the answer is "yes", but need confirmation.</TD> +</TR> + + +</TABLE> + +<A NAME="interoprules"></A><h2>Basic Interop Rules</h2> + +<P>Vanilla +FreeS/WAN implements <A HREF="compat.html#compat">these parts</A> of the +IPSec specifications. You can add more with +<A HREF="http://www.freeswan.ca">Super FreeS/WAN</A>, +but what we offer may be enough for many users.</P> +<UL> +<LI> +To use X.509 certificates with FreeS/WAN, you will need +the <A HREF="http://www.strongsec.org/freeswan">X.509 patch</a> +or <A HREF="http://www.freeswan.ca">Super FreeS/WAN</A>, +which includes that patch.</LI> +<LI> +To use +<A HREF="glossary.html#NAT.gloss">Network Address Translation</A> +(NAT) traversal +with FreeS/WAN, you will need Arkoon Network Security's +<A HREF="http://open-source.arkoon.net">NAT traversal patch</A> +or <A HREF="http://www.freeswan.ca">Super FreeS/WAN</A>, which includes it. +</LI> +</UL> + + +<P>We offer a set of proposals which is not user-adjustable, but covers +all combinations that we can offer. +FreeS/WAN always proposes triple DES encryption and +Perfect Forward Secrecy (PFS). +In addition, we propose Diffie Hellman groups 5 and 2 +(in that order), and MD5 and SHA-1 hashes. +We accept the same proposals, in the same order of preference. +</P> + +<P>Other interop notes:</P> +<UL> +<LI> +A <A HREF="http://lists.freeswan.org/archives/users/2003-September/msg00462.html">SHA-1 +bug in FreeS/WAN 2.00, 2.01 and 2.02</A> may affect some +interop scenarios. It does not affect 1.x versions, and is fixed in 2.03 and +later. +</LI> +<LI> +Some other implementations will close a connection with FreeS/WAN +after some time. This may be a problem with rekey lifetimes. Please see +<A HREF="http://lists.freeswan.org/archives/users/2003-October/msg00293.html"> +this tip</A> and +<A HREF="http://lists.freeswan.org/pipermail/users/2001-December/005758.html"> +this workaround</A>. +</LI> +</UL> + +<H2>Longer Stories</H2> + + +<H3>For <EM>More Compatible</EM> Implementations</H3> + + +<H4><A NAME="freeswan">FreeS/WAN</A></H4> + +<P> +See our documentation at <A HREF="http://www.freeswan.org">freeswan.org</A> +and the Super FreeS/WAN docs at +<A HREF="http://www.freeswan.ca">freeswan.ca</A>. +Some user-written HOWTOs for FreeS/WAN-FreeS/WAN connections +are listed in <A HREF="intro.html#howto">our Introduction</A>. +</P> + +<P>See also:</P> + +<UL> +<LI> +<A HREF="http://lugbe.ch/action/reports/ipsec_htbe.phtml">A German FreeS/WAN-FreeS/WAN page by Markus Wernig (X.509)</A> +</LI> +</UL> + + +<P><A HREF="#freeswan.top">Back to chart</A></P> + + +<H4><A NAME="isakmpd">isakmpd (OpenBSD)</A></H4> + +<P><A HREF="http://www.openbsd.org/faq/faq13.html">OpenBSD FAQ: Using IPsec</A><BR> +<A HREF="http://www.rommel.stw.uni-erlangen.de/~hshoexer/ipsec-howto/HOWTO.html">Hans-Joerg Hoexer's interop Linux-OpenBSD (PSK)</A><BR> +<A HREF="http://www.segfault.net/ipsec/">Skyper's configuration (PSK)</A> +<BR> +<A HREF="http://www.hsc.fr/ressources/ipsec/ipsec2001/#config"> +French page with configs (X.509)</A> + + +</P> + +<P><A HREF="#isakmpd.top">Back to chart</A></P> + + +<H4><A NAME="kame">Kame</A></H4> + +<UL> +<LI>For FreeBSD and NetBSD. Ships with Mac OS X; see also our +<A HREF="#apple">Mac</A> section.</LI> +<LI>Also known as <EM>racoon</EM>, its keying daemon.</LI> +</UL> + +<P><A HREF="http://www.kame.net">Kame homepage, with FAQ</A><BR> +<A HREF="http://www.netbsd.org/Documentation/network/ipsec">NetBSD's IPSec FAQ</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/12/msg00560.html">Ghislaine's post explaining some interop peculiarities</A> +</P> +<P> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/09/msg00511.html">Itojun's Kame-FreeS/WAN interop tips (PSK)</A><BR> +<A HREF="http://www.hsc.fr/ressources/ipsec/ipsec2000">Ghislaine Labouret's French page with links to matching FreeS/WAN and Kame configs (RSA)</A><BR> +<A HREF="http://lugbe.ch/lostfound/contrib/freebsd_router/">Markus Wernig's +HOWTO (X.509, BSD gateway)</A><BR> +<A HREF="http://web.morgul.net/~frodo/docs/kame+freeswan_interop.html">Frodo's Kame-FreeS/WAN interop (X.509)</A><BR> +<A HREF="http://www.wavesec.org/kame.phtml">Kame as a WAVEsec client.</A> +</P> + +<P><A HREF="#kame.top">Back to chart</A></P> + + +<H4><A NAME="mcafee">PGPNet/McAfee</A></H4> + +<P> +<UL> +<LI>Now called McAfee VPN Client.</LI> +<LI>PGPNet also came in a freeware version which did not support subnets</LI> +<LI>To support dhcp-over-ipsec, you need the X.509 patch, which is included in +<A HREF="http://www.freeswan.ca">Super FreeS/WAN</A>. +</LI> +</UL> +<P> +<A HREF="http://www.freeswan.ca/docs/WindowsInterop">Tim Carr's Windows Interop Guide (X.509)</A><BR> +<A HREF="http://www.rommel.stw.uni-erlangen.de/~hshoexer/ipsec-howto/HOWTO.html#Interop2" +>Hans-Joerg Hoexer's Guide for Linux-PGPNet (PSK)</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/04/msg00339.html">Kai Martius' instructions using RSA Key-Extractor Tool (RSA)</A><BR> + <A HREF="http://www.zengl.net/freeswan/english.html">Christian Zeng's page (RSA)</A> based on Kai's work. English or German.<BR> +<A HREF="http://tirnanog.ls.fi.upm.es/CriptoLab/Biblioteca/InfTech/InfTech_CriptoLab.htm"> +Oscar Delgado's PDF (X.509, no configs)</A><BR> +<A HREF="http://www-ec.njit.edu/~rxt1077/Howto.txt">Ryan's HOWTO for FreeS/WAN-PGPNet (X.509)</A>. Through a Linksys Router with IPsec Passthru enabled.<BR> +<A HREF="http://jixen.tripod.com/#RW-PGP-to-Fwan">Jean-Francois Nadeau's Practical Configuration (Road Warrior with PSK)</A><BR> +<A HREF="http://www.evolvedatacom.nl/freeswan.html#toc">Wouter Prins' HOWTO (Road Warrior with X.509)</A><BR> +</P> +<P> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/01/msg00271.html">Rekeying problem with FreeS/WAN and older PGPNets</A><BR> +</P> + +<P><A HREF="http://www.strongsec.com/freeswan/dhcprelay/index.htm"> +DHCP over IPSEC HOWTO for FreeS/WAN (requires X.509 and dhcprelay patches) +</A> +</P> + +<P><A HREF="#mcafee.top">Back to chart</A></P> + + +<H4><A NAME="microsoft">Microsoft Windows 2000/XP</A></H4> + +<UL> +<LI>IPsec comes with Win2k, and with XP Support Tools. May require +<A HREF="http://www.microsoft.com/windows2000/downloads/recommended/encryption/default.asp"> High Encryption Pack</A>. WinXP users have also reported better +results with Service Pack 1.</LI> +<LI>The Road Warrior setup works either way round. Windows (XP or 2K) IPsec +can connect as a Road Warrior to FreeS/WAN. +However, FreeS/WAN can also successfully connect as a Road +Warrior to Windows IPsec (see Nate Carlson's configs below).</LI> +<LI>FreeS/WAN version 1.92 or later is required to avoid an interoperation +problem with Windows native IPsec. Earlier FreeS/WAN versions +did not process the Commit Bit as Windows native IPsec expected.</LI> +</UL> + +<P> +<A HREF="http://www.freeswan.ca/docs/WindowsInterop">Tim Carr's Windows Interop Guide (X.509)</A><BR> + +<A HREF="http://ipsec.math.ucla.edu/services/ipsec.html">James Carter's +instructions (X.509, NAT-T)</A><BR> + +<A HREF="http://jixen.tripod.com/#Win2000-Fwan"> +Jean-Francois Nadeau's Net-net Configuration (PSK)</A><BR> + +<A HREF="http://security.nta.no/freeswan-w2k.html"> +Telenor's Node-node Config (Transport-mode PSK)</A><BR> + +<A HREF="http://vpn.ebootis.de">Marcus Mueller's HOWTO using his VPN config tool (X.509).</A> Tool also works with PSK.<BR> + +<A HREF="http://www.natecarlson.com/include/showpage.php?cat=linux&page=ipsec-x509"> +Nate Carlson's HOWTO using same tool (Road Warrior with X.509)</A>. Unusually, +FreeS/WAN is the Road Warrior here.<BR> + +<A HREF="http://tirnanog.ls.fi.upm.es/CriptoLab/Biblioteca/InfTech/InfTech_CriptoLab.htm"> +Oscar Delgado's PDF (X.509, no configs)</A><BR> + +<A HREF="http://lists.freeswan.org/pipermail/users/2003-July/022425.html">Tim Scannell's Windows XP Additional Checklist (X.509)</A><BR> +</P> + +<!-- Note to self: Include L2TP references? --> + +<P> +<A HREF="http://www.microsoft.com/windows2000/en/server/help/default.asp?url=/windows2000/en/server/help/sag_TCPIP_ovr_secfeatures.htm"> +Microsoft's page on Win2k TCP/IP security features</A><BR> + +<A HREF="http://support.microsoft.com/support/kb/articles/Q257/2/25.ASP"> +Microsoft's Win2k IPsec debugging tips</A><BR> + +<!-- Alt-URL http://support.microsoft.com/default.aspx?scid=kb;EN-US;q257225 +Perhaps newer? --> + +<A HREF="http://www.wired.com/news/technology/0,1282,36336,00.html">MS VPN may fall back to 1DES</A> +</P> + +<P><A HREF="#microsoft.top">Back to chart</A></P> + + +<H4><A NAME="ssh">SSH Sentinel</A></H4> + +<UL> +<LI>Popular and well tested.</LI> +<LI>Also rebranded in <A HREF="http://www.zyxel.com">Zyxel Zywall</A>. +Our Zyxel interop notes are <A HREF="#zyxel">here</A>.</LI> +<LI> +SSH supports IPsec-over-UDP NAT traversal. +</LI> +<LI>There is this +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/12/msg00370.html"> +potential problem</A> if you're not using the Legacy Proposal option. +</UL> + +<P> +<A HREF="http://www.ssh.com/support/sentinel/documents.cfm">SSH's Sentinel-FreeSWAN interop PDF (X.509)</A><BR> +<A HREF="http://www.nadmm.com/show.php?story=articles/vpn.inc">Nadeem Hassan's +SUSE-to-Sentinel article (Road warrior with X.509)</A><BR> +<A HREF="http://www.zerozone.it/documents/Linux/HowTo/VPN-IPsec-Freeswan-HOWTO.html">O-Zone's Italian HOWTO (Road Warrior, X.509, DHCP)</A><BR> +</P> + + +<P><A HREF="#ssh.top">Back to chart</A></P> + + + +<H4><A NAME="safenet">Safenet SoftPK/SoftRemote</A></H4> + +<UL> +<LI>People recommend SafeNet as a low cost Windows client.</LI> +<LI>SoftRemote seems to be the newer name for SoftPK.</LI> +</UL> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2001-November/005061.html"> +Whit Blauvelt's SoftRemote tips</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-October/015591.html"> +Tim Wilson's tips (X.509)</A> +<A HREF="http://lists.freeswan.org/archives/users/2003-October/msg00607.html">Workaround for a "gotcha"</A> +</P> + +<P> +<A HREF="http://jixen.tripod.com/#Rw-IRE-to-Fwan">Jean-Francois Nadeau's +Practical Configuration (Road Warrior with PSK)</A><BR> +<A HREF="http://www.terradoncommunications.com/security/whitepapers/safe_net-to-free_swan.pdf"> +Terradon Communications' PDF (Road Warrior with PSK)</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-October/?????.html"> +Seaan.net's PDF (Road Warrior to Subnet, with PSK) +</A><BR> +<A HREF="http://www.redbaronconsulting.com/freeswan/fswansafenet.pdf"> +Red Baron Consulting's PDF (Road Warrior with X.509)</A> +</P> + +<P><A HREF="#safenet.top">Back to chart</A></P> + + + + + + + + +<H3>For <EM>Other Implementations</EM></H3> + + + +<H4><A NAME="6wind">6Wind</A></H4> + +<P> + +<A HREF="http://www.hsc.fr/ressources/ipsec/ipsec2001/#config"> +French page with configs (X.509)</A> + +</P> + +<P><A HREF="#6wind.top">Back to chart</A></P> + + + +<H4><A NAME="alcatel">Alcatel Timestep</A></H4> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-June/011878.html"> +Alain Sabban's settings (PSK or PSK road warrior; through static NAT)</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/1999/06/msg00100.html"> +Derick Cassidy's configs (PSK)</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/1999/08/msg00194.html"> +David Kerry's Timestep settings (PSK)</A> +<BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-August/013711.html"> +Kevin Gerbracht's ipsec.conf (X.509)</A> +</P> + +<P><A HREF="#alcatel.top">Back to chart</A></P> + + + +<H4><A NAME="apple">Apple Macintosh System 10+</A></H4> + +<UL> +<LI>Since the system is based on FreeBSD, this should +interoperate <A HREF="#kame">just like FreeBSD</A>. +</LI> + +<LI> +To use Appletalk over IPsec tunnels, +<A HREF="http://lists.freeswan.org/pipermail/users/2001-November/005116.html">run +it over TCP/IP</A>, or use +Open Door Networks' Shareway IP tool, +<A HREF="http://lists.freeswan.org/pipermail/users/2001-November/005426.html">described +here.</A> +</LI> + +<LI>See also the <A HREF="#equinux">Equinux VPN Tracker</A> +for Mac OS X.</LI> +</UL> + + +<P> +<A HREF="http://ipsec.math.ucla.edu/services/ipsec.html">James Carter's +instructions (X.509, NAT-T)</A> +</P> + + +<P><A HREF="#apple.top">Back to chart</A></P> + + + + + + +<H4><A NAME="ashleylaurent">AshleyLaurent VPCom</A></H4> + +<P> +<A HREF="http://www.ashleylaurent.com/newsletter/01-28-00.htm"> +Successful interop report, no details</A> +</P> + +<P><A HREF="#ashleylaurent.top">Back to chart</A></P> + + +<H4><A NAME="borderware">Borderware</A></H4> + +<UL> +<LI>I suspect the Borderware client is a rebranded Safenet. +If that's true, our <A HREF="#safenet">Safenet section</A> will help.</LI> +</UL> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-March/008288.html"> +Philip Reetz' configs (PSK)</A><BR> + +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/09/msg00217.html"> +Borderware server does not support FreeS/WAN road warriors</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-February/007733.html"> +Older Borderware may not support Diffie Hellman groups 2, 5</A><BR> +</P> + + +<P><A HREF="#borderware.top">Back to chart</A></P> + + + +<H4><A NAME="checkpoint">Check Point VPN-1 or FW-1</A></H4> + +<UL> +<LI> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00099.html"> +Caveat about IP-range inclusion on Check Point.</A> +</LI> +<LI> +Some versions of Check Point may require an aggressive mode patch to +interoperate with FreeS/WAN.<BR> +<A HREF="http://www.freeswan.ca/code/super-freeswan">Super FreeS/WAN</A> +now features this patch. +<!-- +<A HREF="http://www.freeswan.ca/patches/aggressivemode">Steve Harvey's +aggressive mode patch for FreeS/WAN 1.5</A> +--> +</LI> +<LI> +<LI>A Linux FreeS/WAN-Checkpoint connection may close after some time. Try +<A HREF="http://lists.freeswan.org/archives/users/2003-October/msg00293.html">this tip</A> toward a workaround. +</LI> +</UL> + +<P> +<A HREF="http://www.fw-1.de/aerasec/ng/vpn-freeswan/CPNG+Linux-FreeSWAN.html"> +AERAsec's Firewall-1 NG site (PSK, X.509, Road Warrior with X.509, +other algorithms)</A><BR> + +<A HREF="http://www.fw-1.de/aerasec/ng/vpn-freeswan/CPNG+Linux-FreeSWAN.html#support-matrix"> +AERAsec's detailed Check Point-FreeS/WAN support matrix</A><BR> +<A HREF="http://support.checkpoint.com/kb/docs/public/firewall1/4_1/pdf/fw-linuxvpn.pdf">Checkpoint.com PDF: Linux as a VPN Client to FW-1 (PSK)</A><BR> + +<A HREF="http://www.phoneboy.com">PhoneBoy's Check Point FAQ (on Check Point +only, not FreeS/WAN)</A><BR> + +</P> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2001-August/002351.html">Chris +Harwell's tips & FreeS/WAN configs (PSK)</A><BR> + +<A HREF="http://lists.freeswan.org/pipermail/users/2002-April/009362.html">Daniel +Tombeil's configs (PSK)</A> + +</P> + +<P><A HREF="#checkpoint.top">Back to chart</A></P> + + +<H4><A NAME="cisco">Cisco</A></H4> + +<UL> +<LI> +Cisco supports IPsec-over-UDP NAT traversal. +</LI> +<LI>Cisco VPN Client appears to use nonstandard IPsec and +does not work with FreeS/WAN. <A HREF="https://mj2.freeswan.org/archives/2003-August/maillist.html">This message</A> concerns Cisco VPN Client 4.01. +<!-- fix link --> +</LI> +<LI>A Linux FreeS/WAN-Cisco connection may close after some time. +<A HREF="http://lists.freeswan.org/pipermail/users/2001-December/005758.html"> +Here</A> +is a workaround, and +<A HREF="http://lists.freeswan.org/archives/users/2003-October/msg00293.html">here</A> + is another comment on the same subject.</LI> +<LI><A HREF="http://www.cisco.com/univercd/cc/td/doc/product/software/ios120/120newft/120t/120t2/3desips.htm">Older Ciscos</A> +purchased outside the United States may not have 3DES, which FreeS/WAN requires.</LI> +<LI><A HREF="http://lists.freeswan.org/pipermail/users/2001-June/000406.html">RSA keying may not be possible between Cisco and FreeS/WAN.</A> +<LI><A HREF="http://lists.freeswan.org/pipermail/users/2001-October/004357.html">In +ipsec.conf, VPN3000 DN (distinguished name) must be in binary (X.509 only)</A></LI> + + +</UL> + + +<P> +<A HREF="http://rr.sans.org/encryption/cisco_router.php">SANS Institute HOWTO (PSK).</A> Detailed, with extensive references.<BR> +<A HREF="http://www.worldbank.ro/IPSEC/cisco-linux.txt">Short HOWTO (PSK)</A><BR> +<A HREF="http://www.hsc.fr/ressources/ipsec/ipsec2001/#config"> +French page with configs for Cisco IOS, PIX and VPN 3000 (X.509)</A> +<BR> + +<A HREF="http://lists.freeswan.org/pipermail/users/2001-August/002966.html">Dave +McFerren's sample configs (PSK)</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2001-September/003422.html">Wolfgang +Tremmel's sample configs (PSK road warrior)</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00578.html"> +Old doc from Pete Davis, with William Watson's updated Tips (PSK)</A><BR> +</P> + +<P><STRONG>Some PIX specific information:</STRONG><BR> + +<A HREF="http://www.wlug.org.nz/FreeSwanToCiscoPix"> +Waikato Linux Users' Group HOWTO. Nice detail (PSK) +</A><BR> +<A HREF="http://www.johnleach.co.uk/documents/freeswan-pix/freeswan-pix.html"> +John Leach's configs (PSK) +</A><BR> +<A HREF="http://www.diverdown.cc/vpn/freeswanpix.html"> +Greg Robinson's settings (PSK) +</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-February/007901.html"> +Scott's ipsec.conf for PIX (PSK, FreeS/WAN side only)</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2001-October/003949.html">Rick +Trimble's PIX and FreeS/WAN settings (PSK)</A><BR> +</P> + + + +<P><A href="http://www.cisco.com/public/support/tac"> +Cisco VPN support page</A><BR> +<A href="http://www.ieng.com/warp/public/707/index.shtml#ipsec"> +Cisco IPsec information page</A> +</P> + +<P><A HREF="#cisco.top">Back to chart</A></P> + + + + +<H4><A NAME="equinux">Equinux VPN tracker (for Mac OS X)</A></H4> + +<UL> +<LI>Graphical configurator for Mac OS X IPsec. May be an interface +to the <A HREF="#apple">native Mac OS X IPsec</A>, which is essentially +<A HREF="#kame">KAME</A>.</LI> +<LI>To use Appletalk over IPsec tunnels, +<A HREF="http://lists.freeswan.org/pipermail/users/2001-November/005116.html">run +it over TCP/IP</A>, or use +Open Door Networks' Shareway IP tool, +<A HREF="http://lists.freeswan.org/pipermail/users/2001-November/005426.html">described +here.</A> </LI> +</UL> + + +<P> +Equinux provides <A HREF="http://www.equinux.com/download/HowTo_FreeSWAN.pdf">this +excellent interop PDF</A> (PSK, RSA, X.509). +</P> + +<P><A HREF="#equinux.top">Back to chart</A></P> + + +<H4><A NAME="fsecure">F-Secure</A></H4> + +<UL> +<LI> +<!-- <A HREF="http://lists.freeswan.org/pipermail/users/2002-February/007596.html"> --> +F-Secure supports IPsec-over-UDP NAT traversal. +</LI> +</UL> + +<P><A HREF="http://www.pingworks.de/tech/vpn/vpn.txt">pingworks.de's + "Connecting F-Secure's VPN+ to Linux FreeS/WAN" (PSK road warrior)</A><BR> + <A HREF="http://www.pingworks.de/tech/vpn/vpn.pdf">Same thing as PDF</A><BR> +<A HREF="http://www.exim.org/pipermail/linux-ipsec/Week-of-Mon-20010122/000061.html">Success report, no detail (PSK)</A><BR> +<A HREF="http://www.exim.org/pipermail/linux-ipsec/Week-of-Mon-20010122/000041.html">Success report, no detail (Manual)</A> +</P> + +<!-- Other NAT traversers: +http://lists.freeswan.org/pipermail/users/2002-April/009136.html +and ssh sentinel: +http://lists.freeswan.org/pipermail/users/2001-September/003108.html +--> + +<P><A HREF="#fsecure.top">Back to chart</A></P> + + + +<H4><A NAME="gauntlet">Gauntlet GVPN</A></H4> + +<P> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00535.html">Richard Reiner's ipsec.conf (PSK)</A> +<BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-June/011434.html"> +Might work without that pesky firewall... (PSK)</A><BR> +<!-- insert archive link --> +In late July, 2003 Alexandar Antik reported success interoperating +with Gauntlet 6.0 for Solaris (X.509). Unfortunately the message is not +properly archived at this time. +</P> + +<P><A HREF="#gauntlet.top">Back to chart</A></P> + + + +<H4><A NAME="aix">IBM AIX</A></H4> + +<P><A HREF="http://www-1.ibm.com/servers/esdd/articles/security.html"> +IBM's "Built-In Network Security with AIX" (PSK, X.509)</A><BR> +<A HREF="http://www-1.ibm.com/servers/aix/products/ibmsw/security/vpn/faqandtips/#ques20"> +IBM's tip: importing Linux FreeS/WAN settings into AIX's <VAR>ikedb</VAR> +(PSK)</A> +</P> + +<P><A HREF="#aix.top">Back to chart</A></P> + + + +<H4><A NAME="as400">IBM AS/400</A></H4> + +<UL> +<LI> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-April/009106.html">Road + Warriors may act flaky</A>. +</LI> +</UL> + +<P><A HREF="http://lists.freeswan.org/pipermail/users/2002-September/014264.html"> +Richard Welty's tips and tricks</A><BR> +</P> + +<P><A HREF="#as400.top">Back to chart</A></P> + + + +<H4><A NAME="intel">Intel Shiva LANRover / Net Structure</A></H4> + +<UL> +<LI>Intel Shiva LANRover is now known as Intel Net Structure.</LI> +<LI> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/01/msg00298.html"> +Shiva seems to have two modes: IPsec or the proprietary +"Shiva Tunnel".</A> +Of course, FreeS/WAN will only create IPsec tunnels. +</LI> + +<LI> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00293.html"> +AH may not work for Shiva-FreeS/WAN.</A> +That's OK, since FreeS/WAN has phased out the use of AH. +</LI> +</UL> + +<P> +<A HREF="http://snowcrash.tdyc.com/freeswan/"> +Snowcrash's configs (PSK)</A><BR> + +<A HREF="http://www.opus1.com/vpn/index.html"> +Old configs from an interop (PSK)</A><BR> + +<A HREF="http://lists.freeswan.org/pipermail/users/2001-October/003831.html"> +The day Shiva tickled a Pluto bug (PSK)</A><BR> + + +<A HREF="http://lists.freeswan.org/pipermail/users/2001-October/004270.html"> +Follow up: success!</A> +</P> + +<P><A HREF="#intel.top">Back to chart</A></P> + + + +<H4><A NAME="lancom">LanCom (formerly ELSA)</A></H4> + +<UL> +<LI>This router is popular in Germany. +</UL> + +<P> +Jakob Curdes successfully created a PSK connection with the LanCom 1612 in +August 2003. +<!-- add ML link when it appears --> +</P> + +<P><A HREF="#lancom.top">Back to chart</A></P> + + + +<H4><A NAME="linksys">Linksys</A></H4> + +<UL> +<LI>Linksys may be used as an IPsec tunnel endpoint, <STRONG>OR</STRONG> +as a router in "IPsec passthrough" mode, so that the IPsec tunnel +passes through the Linksys. +</LI> +</UL> + +<H5>As tunnel endpoint</H5> +<P> +<A HREF="http://www.freeswan.ca/docs/BEFVP41/"> +Ken Bantoft's instructions (Road Warrior with PSK)</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-February/007814.html"> +Nate Carlson's caveats</A> +</P> + +<H5>In IPsec passthrough mode</H5> +<P> +<A HREF="http://www-ec.njit.edu/~rxt1077/Howto.txt"> +Sample HOWTO through a Linksys Router</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2002/02/msg00114.html"> +Nadeem Hasan's configs</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2002/02/msg00180.html"> +Brock Nanson's tips</A><BR> +</P> + +<P><A HREF="#linksys.top">Back to chart</A></P> + + +<H4><A NAME="lucent">Lucent</A></H4> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-May/010976.html"> +Partial success report; see also the next message in thread</A> +</P> +<!-- section done --> + +<P><A HREF="#lucent.top">Back to chart</A></P> + + +<H4><A NAME="netasq">Netasq</A></H4> + +<P> +<A HREF="http://www.hsc.fr/ressources/ipsec/ipsec2001/#config"> +French page with configs (X.509)</A> + +</P> +<!-- section done --> + +<P><A HREF="#netasq.top">Back to chart</A></P> + + + +<H4><A NAME="netcelo">Netcelo</A></H4> + +<P> +<A HREF="http://www.hsc.fr/ressources/ipsec/ipsec2001/#config"> +French page with configs (X.509)</A> + +<!-- section done --> + +</P> + +<P><A HREF="#netcelo.top">Back to chart</A></P> + + + +<H4><A NAME="netgear">Netgear fvs318</A></H4> + +<UL> +<LI>With a recent Linux FreeS/WAN, you will require the latest +(12/2002) Netgear firmware, which supports Diffie-Hellman (DH) group 2. +For security reasons, we phased out DH 1 after Linux FreeS/WAN 1.5. +</LI> +<LI> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-June/011833.html"> +This message</A> reports the incompatibility between Linux FreeS/WAN 1.6+ +and Netgear fvs318 without the firmware upgrade. +</LI> +<LI>We believe Linux FreeS/WAN 1.5 and earlier will interoperate with +any NetGear firmware. +</LI> +</UL> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2003-February/017891.html"> +John Morris' setup (PSK)</A> +</P> + +<P><A HREF="#netgear.top">Back to chart</A></P> + + + +<H4><A NAME="netscreen">Netscreen 100 or 5xp</A></H4> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-August/013409.html"> +Errol Neal's settings (PSK)</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-October/015265.html"> +Corey Rogers' configs (PSK, no PFS)</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-August/013051.html"> +Jordan Share's configs (PSK, 2 subnets, through static NAT)</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/08/msg00404.html"> +Set src proxy_id to your protected subnet/mask</A><BR> + +<A HREF="http://www.hsc.fr/ressources/ipsec/ipsec2001/#config"> +French page with ipsec.conf, Netscreen screen shots (X.509, may +need to revert to PSK...)</A> + +</P> +<P> +<A HREF="http://archives.neohapsis.com/archives/sf/linux/2001-q2/0123.html"> +A report of a company using Netscreen with FreeS/WAN on a large scale +(FreeS/WAN road warriors?)</A> +</P> + +<P><A HREF="#netscreen.top">Back to chart</A></P> + + + +<H4><A NAME="nortel">Nortel Contivity</A></H4> + +<UL> +<LI> +Nortel supports IPsec-over-UDP NAT traversal. +</LI> + +<LI> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00417.html"> +Some older versions of Contivity and FreeS/WAN will not communicate.</A> +</LI> + +<LI> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-May/010924.html"> +FreeS/WAN cannot be used as a "client" to a Nortel Contivity server, +but can be used as a branch-office tunnel.</A> +</LI> + +<!-- Probably obsoleted by Ken's post +<LI> +(Matthias siebler from old interop) +At one point you could not configure Nortel-FreeS/WAN tunnels as +"Client Tunnels" since FreeS/WAN does not support Aggressive Mode. +Current status of this problem: unknown. +<LI> +<A HREF="http://lists.freeswan.org/pipermail/users/2001-November/004612.html"> +How do we map group and user passwords onto the data that FreeS/WAN wants? +</A> +</LI> +--> + +<LI> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-October/015455.html"> +Contivity does not send Distinguished Names in the order FS wants them (X.509). +</A> +</LI> + +<LI> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/03/msg00137.html"> +Connections may time out after 30-40 minutes idle.</A> +</LI> + +</UL> + +<P> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/03/msg00137.html"> +JJ Streicher-Bremer's mini HOWTO for old & new software. (PSK with two subnets) +</A><BR> +<A HREF="http://www.hsc.fr/ressources/ipsec/ipsec2001/#config"> +French page with configs (X.509)</A>. This succeeds using the above X.509 tip. +</P> + +<!-- I could do more searching but this is a solid start. --> + +<P><A HREF="#nortel.top">Back to chart</A></P> + + +<H4><A NAME="radguard">Radguard</A></H4> + +<P> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/05/msg00009.html"> +Marko Hausalo's configs (PSK).</A> Note: These do create a connection, +as you can see by "IPsec SA established".<BR> + +<A HREF="http://lists.freeswan.org/pipermail/users/2002-October/???.html"> +Claudia Schmeing's comments</A> +</P> + +<P><A HREF="#radguard.top">Back to chart</A></P> + + +<H4><A NAME="raptor">Raptor (NT or Solaris)</A></H4> + +<P> + +<UL> +<LI>Now known as Symantec Enterprise Firewall.</LI> +<LI>The Raptor does not normally come with X.509, but this may be available as +an add-on.</LI> +<LI><A HREF="http://lists.freeswan.org/pipermail/users/2002-May/010256.html"> +Raptor requires alphanumberic PSK values, whereas FreeS/WAN uses hex.</A> +</LI> +<LI>Raptor's tunnel endpoint may be a host, subnet or group of subnets +(see +<A HREF="http://lists.freeswan.org/pipermail/design/2001-November/001295.html"> +this message</A> +). FreeS/WAN cannot handle the group of subnets; you +must create separate connections for each in order to interoperate.</LI> +<LI> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-May/010113.html"> +Some versions of Raptor accept only single DES. +</A> +According to this German message, +<A HREF="http://radawana.cg.tuwien.ac.at/mail-archives/lll/200012/msg00065.html"> +the Raptor Mobile Client demo offers single DES only.</A> +</LI> +</UL> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-January/006935.html"> +Peter Mazinger's settings (PSK)</A><BR> + +<A HREF="http://lists.freeswan.org/pipermail/users/2001-November/005522.html"> +Peter Gerland's configs (PSK)</A><BR> + +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/07/msg00597.html"> +Charles Griebel's configs (PSK).</A><BR> + +<A HREF="http://lists.freeswan.org/pipermail/users/2002-July/012275.html"> +Lumir Srch's tips (PSK) +</A> +</P> + +<P> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/05/msg00214.html"> +John Hardy's configs (Manual)</A><BR> + +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/01/msg00236.html"> +Older Raptors want 3DES keys in 3 parts (Manual).</A><BR> + +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/06/msg00480.html"> +Different keys for each direction? (Manual)</A><BR> + +</P> + +<P><A HREF="#raptor.top">Back to chart</A></P> + + + +<H4><A NAME="redcreek">Redcreek Ravlin</A></H4> + +<UL> +<LI>Known issue #1: The Ravlin expects a quick mode renegotiation right +after every Main Mode negotiation. +</LI> +<LI> +Known issue #2: The Ravlin tries to negotiate a zero +connection lifetime, which it takes to mean "infinite". +<A HREF="http://www.bear-cave.org.uk/linux/ravlin/">Jim Hague's patch</A> +addresses both issues. +</LI> +<LI> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/03/msg00191.html"> +Interop works with Ravlin Firmware > 3.33. Includes tips (PSK).</A> +</LI> +</UL> + +<P><A HREF="#redcreek.top">Back to chart</A></P> + + + +<H4><A NAME="sonicwall">SonicWall</A></H4> + +<UL> +<LI><A HREF="http://lists.freeswan.org/pipermail/users/2001-June/000998.html"> +Sonicwall cannot be used for Road Warrior setups</A></LI> +<LI> +At one point, <A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/05/msg00217.html"> +only Sonicwall PRO supported triple DES</A>.</LI> +<LI> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-March/008600.html"> +Older Sonicwalls (before Nov 2001) feature Diffie Hellman group 1 +only</A>.</LI> +</UL> + +<P> +<A HREF="http://www.xinit.cx/docs/freeswan.html">Paul Wouters' config (PSK)</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00073.html"> +Dilan Arumainathan's configuration (PSK)</A><BR> +<A HREF="http://www.gravitas.co.uk/vpndebug">Dariush's setup... only opens +one way (PSK)</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2003-July/022302.html"> +Andreas Steffen's tips (X.509)</A><BR> + +</P> + +<P><A HREF="#sonicwall.top">Back to chart</A></P> + + + +<H4><A NAME="sun">Sun Solaris</A></H4> + +<UL> +<LI> +Solaris 8+ has a native (in kernel) IPsec implementation. +</LI> +<LI> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-May/010503.html"> +Solaris does not seem to support tunnel mode, but you can make +IP-in-IP tunnels instead, like this.</A> +</LI> +</UL> +<P> + +<A HREF="http://lists.freeswan.org/pipermail/users/2003-June/022216.html">Reports of some successful interops</A> from a fellow @sun.com. +See also <A HREF="http://lists.freeswan.org/pipermail/users/2003-July/022247.html">these follow up posts</A>.<BR> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/03/msg00332.html"> +Aleks Shenkman's configs (Manual in transport mode) +</A><BR> +<!--sparc 64 stuff goes where?--> +</P> + +<P><A HREF="#solaris.top">Back to chart</A></P> + + + +<H4><A NAME="symantec">Symantec</A></H4> + +<UL> +<LI>The Raptor, covered <A HREF="#raptor">above</A>, is now known as +Symantec Enterprise Firewall.</LI> +<LI>Symantec's "distinguished name" is a KEY_ID. See Andreas Steffen's post, +below.</LI> +</UL> + +<P><A HREF="http://lists.freeswan.org/pipermail/users/2002-April/009037.html"> +Andreas Steffen's configs for Symantec 200R (PSK)</A> +</P> + +<P><A HREF="#symantec.top">Back to chart</A></P> + + + + +<H4><A NAME="watchguard">Watchguard Firebox</A></H4> + +<UL> +<LI>Automatic keying works with WatchGuard 5.0+ only.</LI> +<LI>Seen to interoperate with WatchGuard 1000, II, III; firmware v. 5, 6..</LI> +<LI>For manual keying, Watchguard's Policy Manager expects SPI numbers and +encryption and authentication keys in decimal (not hex).</LI> +</UL> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-July/012595.html"> +WatchGuard's HOWTO (PSK)</A><BR> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-August/013342.html"> +Ronald C. Riviera's Settings (PSK)</A><BR> +<A HREF="http://lists.freeswan.org/archives/users/2003-October/msg00179.html"> +Walter Wickersham's Notes (PSK)</A><BR> + +<A HREF="http://lists.freeswan.org/pipermail/users/2002-October/015587.html"> +Max Enders' Configs (Manual)</A> +</P> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/users/2002-April/009404.html"> +Old known issue with auto keying</A><BR> + +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00124.html"> +Tips on key generation and format (Manual)</A><BR> +</P> + +<P><A HREF="#watchguard.top">Back to chart</A></P> + + + +<H4><A NAME="xedia">Xedia Access Point/QVPN</A></H4> + +<P> +<A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/12/msg00520.html"> +Hybrid IPsec/L2TP connection settings (X.509) +</A><BR> +<A HREF="http://www.sandelman.ottawa.on.ca/ipsec/1999/08/msg00140.html"> + Xedia's LAN-LAN links don't use multiple tunnels +</A><BR> + +<A HREF="http://www.sandelman.ottawa.on.ca/ipsec/1999/08/msg00140.html"> + That explanation, continued +</A> +</P> + +<P><A HREF="#xedia.top">Back to chart</A></P> + + + +<H4><A NAME="zyxel">Zyxel</A></H4> + +<UL> +<LI>The Zyxel Zywall is a rebranded SSH Sentinel box. See also our section +on <A HREF="#ssh">SSH</A>.</LI> +<LI>There seems to be a problem with keeping this connection alive. This is +caused at the Zyxel end. See this brief +<A HREF="http://lists.freeswan.org/archives/users/2003-October/msg00141.html"> +discussion and solution. +</A> +</LI> +</UL> +<P> +<A HREF="http://www.zyxel.com/support/supportnote/zywall/app/zw_freeswan.htm"> +Zyxel's Zywall to FreeS/WAN instructions (PSK)</A><BR> +<A HREF="http://www.zyxel.com/support/supportnote/p652/app/zw_freeswan.htm"> +Zyxel's Prestige to FreeS/WAN instructions (PSK)</A>. Note: not all Prestige +versions include VPN software.<BR> + +<A HREF="http://www.lancry.net/techdocs/freeswan-zyxel.txt">Fabrice Cahen's + HOWTO (PSK)</A><BR> + +</P> + +<P><A HREF="#zyxel.top">Back to chart</A></P> + + + +<!-- SAMPLE ENTRY + +<H4><A NAME="timestep">Timestep</A></H4> + +<P>Text goes here. +</P> + +--> +</BODY></HTML> + diff --git a/doc/src/intro.html b/doc/src/intro.html new file mode 100644 index 000000000..09c352c00 --- /dev/null +++ b/doc/src/intro.html @@ -0,0 +1,887 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>Introduction to FreeS/WAN</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, introduction"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: intro.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="intro">Introduction</a></h1> + +<p>This section gives an overview of:</p> +<ul> + <li>what IP Security (IPsec) does</li> + <li>how IPsec works</li> + <li>why we are implementing it for Linux</li> + <li>how this implementation works</li> +</ul> + +<p>This section is intended to cover only the essentials, <em>things you +should know before trying to use FreeS/WAN.</em></p> + +<p>For more detailed background information, see the <a +href="politics.html#politics">history and politics</a> and +<a href="ipsec.html#ipsec.detail">IPsec protocols</a> sections.</p> + +<h2><a name="ipsec.intro">IPsec, Security for the Internet Protocol</a></h2> + +<p>FreeS/WAN is a Linux implementation of the IPsec (IP security) protocols. +IPsec provides <a href="glossary.html#encryption">encryption</a> and <a +href="glossary.html#authentication">authentication</a> services at the IP +(Internet Protocol) level of the network protocol stack.</p> + +<p>Working at this level, IPsec can protect any traffic carried over IP, +unlike other encryption which generally protects only a particular +higher-level protocol -- <a href="glossary.html#PGP">PGP</a> for mail, <a +href="glossary.html#SSH">SSH</a> for remote login, <a +href="glossary.html#SSL">SSL</a> for web work, and so on. This approach has +both considerable advantages and some limitations. For discussion, see our <a +href="ipsec.html#others">IPsec section</a></p> + +<p>IPsec can be used on any machine which does IP networking. Dedicated IPsec +gateway machines can be installed wherever required to protect traffic. IPsec +can also run on routers, on firewall machines, on various application +servers, and on end-user desktop or laptop machines.</p> + +<p>Three protocols are used</p> +<ul> + <li><a href="glossary.html#AH">AH</a> (Authentication Header) provides a + packet-level authentication service</li> + <li><a href="glossary.html#ESP">ESP</a> (Encapsulating Security Payload) + provides encryption plus authentication</li> + <li><a href="glossary.html#IKE">IKE</a> (Internet Key Exchange) negotiates + connection parameters, including keys, for the other two</li> +</ul> + +<p>Our implementation has three main parts:</p> +<ul> + <li><a href="glossary.html#KLIPS">KLIPS</a> (kernel IPsec) implements AH, + ESP, and packet handling within the kernel</li> + <li><a href="glossary.html#Pluto">Pluto</a> (an IKE daemon) implements IKE, + negotiating connections with other systems</li> + <li>various scripts provide an adminstrator's interface to the + machinery</li> +</ul> + +<p>IPsec is optional for the current (version 4) Internet Protocol. FreeS/WAN +adds IPsec to the Linux IPv4 network stack. Implementations of <a +href="glossary.html#ipv6.gloss">IP version 6</a> are required to include +IPsec. Work toward integrating FreeS/WAN into the Linux IPv6 stack has <a +href="compat.html#ipv6">started</a>.</p> + +<p>For more information on IPsec, see our +<a href="ipsec.html#ipsec.detail">IPsec protocols</a> section, +our collection of <a href="web.html#ipsec.link">IPsec +links</a> or the <a href="rfc.html#RFC">RFCs</a> which are the official +definitions of these protocols.</p> + +<h3><a name="intro.interop">Interoperating with other IPsec +implementations</a></h3> + +<p>IPsec is designed to let different implementations work together. We +provide:</p> +<ul> + <li>a <a href="web.html#implement">list</a> of some other + implementations</li> + <li>information on <a href="interop.html#interop">using FreeS/WAN + with other implementations</a></li> +</ul> + +<p>The VPN Consortium fosters cooperation among implementers and +interoperability among implementations. Their <a +href="http://www.vpnc.org/">web site</a> has much more information.</p> + +<h3><a name="advantages">Advantages of IPsec</a></h3> + +<p>IPsec has a number of security advantages. Here are some independently +written articles which discuss these:</p> + +<P> +<A HREF="http://www.sans.org/rr/">SANS institute papers</A>. See the section +on Encryption &VPNs. +<BR> +<A HREF="http://www.cisco.com/en/US/netsol/ns110/ns170/ns171/ns128/networking_solutions_white_papers_list.html">Cisco's +white papers on "Networking Solutions"</A>. +<BR> +<A HREF="http://iscs.sourceforge.net/HowWhyBrief/HowWhyBrief.html"> +Advantages of ISCS (Linux Integrated Secure Communications System; +includes FreeS/WAN and other software)</A>. + +</P> + + +<h3><a name="applications">Applications of IPsec</a></h3> + +<p>Because IPsec operates at the network layer, it is remarkably flexible and +can be used to secure nearly any type of Internet traffic. Two applications, +however, are extremely widespread:</p> +<ul> + <li>a <a href="glossary.html#VPN">Virtual Private Network</a>, or VPN, + allows multiple sites to communicate securely over an insecure Internet + by encrypting all communication between the sites.</li> + <li>"Road Warriors" connect to the office from home, or perhaps from a + hotel somewhere</li> +</ul> + +<p>There is enough opportunity in these applications that vendors are +flocking to them. IPsec is being built into routers, into firewall products, +and into major operating systems, primarily to support these applications. +See our <a href="web.html#implement">list</a> of implementations for +details.</p> + +<p>We support both of those applications, and various less common IPsec +applications as well, but we also add one of our own:</p> +<ul> + <li>opportunistic encryption, the ability to set up FreeS/WAN gateways so + that any two of them can encrypt to each other, and will do so whenever + packets pass between them.</li> +</ul> + +<p>This is an extension we are adding to the protocols. FreeS/WAN is the +first prototype implementation, though we hope other IPsec implementations +will adopt the technique once we demonstrate it. See <a href="#goals">project +goals</a> below for why we think this is important.</p> + +<p>A somewhat more detailed description of each of these applications is +below. Our <a href="quickstart.html#quick_guide">quickstart</a> section will +show you how to build each of them.</p> + +<h4><a name="makeVPN">Using secure tunnels to create a VPN</a></h4> + +<p>A VPN, or <strong>V</strong>irtual <strong>P</strong>rivate +<strong>N</strong>etwork lets two networks communicate securely when the only +connection between them is over a third network which they do not trust.</p> + +<p>The method is to put a security gateway machine between each of the +communicating networks and the untrusted network. The gateway machines +encrypt packets entering the untrusted net and decrypt packets leaving it, +creating a secure tunnel through it.</p> + +<p>If the cryptography is strong, the implementation is careful, and the +administration of the gateways is competent, then one can reasonably trust +the security of the tunnel. The two networks then behave like a single large +private network, some of whose links are encrypted tunnels through untrusted +nets.</p> + +<p>Actual VPNs are often more complex. One organisation may have fifty branch +offices, plus some suppliers and clients, with whom it needs to communicate +securely. Another might have 5,000 stores, or 50,000 point-of-sale devices. +The untrusted network need not be the Internet. All the same issues arise on +a corporate or institutional network whenever two departments want to +communicate privately with each other.</p> + +<p>Administratively, the nice thing about many VPN setups is that large parts +of them are static. You know the IP addresses of most of the machines +involved. More important, you know they will not change on you. This +simplifies some of the admin work. For cases where the addresses do change, +see the next section.</p> + +<h4><a name="road.intro">Road Warriors</a></h4> + +<p>The prototypical "Road Warrior" is a traveller connecting to home base +from a laptop machine. Administratively, most of the same problems arise for +a telecommuter connecting from home to the office, especially if the +telecommuter does not have a static IP address.</p> + +<p>For purposes of this document:</p> +<ul> + <li>anyone with a dynamic IP address is a "Road Warrior".</li> + <li>any machine doing IPsec processing is a "gateway". Think of the + single-user road warrior machine as a gateway with a degenerate subnet + (one machine, itself) behind it.</li> +</ul> + +<p>These require somewhat different setup than VPN gateways with static +addresses and with client systems behind them, but are basically not +problematic.</p> + +<p>There are some difficulties which appear for some road warrior +connections:</p> +<ul> + <li>Road Wariors who get their addresses via DHCP may have a problem. + FreeS/WAN can quite happily build and use a tunnel to such an address, + but when the DHCP lease expires, FreeS/WAN does not know that. The tunnel + fails, and the only recovery method is to tear it down and re-build + it.</li> + <li>If <a href="glossary.html#NAT.gloss">Network Address Translation</a> + (NAT) is applied between the two IPsec Gateways, this breaks IPsec. IPsec + authenticates packets on an end-to-end basis, to ensure they are not + altered en route. NAT rewrites packets as they go by. See our <a + href="firewall.html#NAT">firewalls</a> document for details.</li> +</ul> + +<p>In most situations, however, FreeS/WAN supports road warrior connections +just fine.</p> + +<h4><a name="opp.intro">Opportunistic encryption</a></h4> + +<p>One of the reasons we are working on FreeS/WAN is that it gives us the +opportunity to add what we call opportuntistic encryption. This means that +any two FreeS/WAN gateways will be able to encrypt their traffic, even if the +two gateway administrators have had no prior contact and neither system has +any preset information about the other.</p> + +<p>Both systems pick up the authentication information they need from the <a +href="glossary.html#DNS">DNS</a> (domain name service), the service they +already use to look up IP addresses. Of course the administrators must put +that information in the DNS, and must set up their gateways with +opportunistic encryption enabled. Once that is done, everything is automatic. +The gateways look for opportunities to encrypt, and encrypt whatever they +can. Whether they also accept unencrypted communication is a policy decision +the administrator can make.</p> + +<p>This technique can give two large payoffs:</p> +<ul> + <li>It reduces the administrative overhead for IPsec enormously. You + configure your gateway and thereafter everything is automatic. The need + to configure the system on a per-tunnel basis disappears. Of course, + FreeS/WAN allows specifically configured tunnels to co-exist with + opportunistic encryption, but we hope to make them unnecessary in most + cases.</li> + <li>It moves us toward a more secure Internet, allowing users to create an + environment where message privacy is the default. All messages can be + encrypted, provided the other end is willing to co-operate. See our <a + href="politics.html#politics">history and politics of cryptography</a> + section for discussion of why we think this is needed.</li> +</ul> + +<p>Opportunistic encryption is not (yet?) a standard part of the IPsec +protocols, but an extension we are proposing and demonstrating. For details +of our design, see <a href="#applied">links</a> below.</p> + +<p>Only one current product we know of implements a form of opportunistic +encryption. <a href="web.html#ssmail">Secure sendmail</a> will automatically +encrypt server-to-server mail transfers whenever possible.</p> + +<h3><a name="types">The need to authenticate gateways</a></h3> + +<p>A complication, which applies to any type of connection -- VPN, Road +Warrior or opportunistic -- is that a secure connection cannot be created +magically. <em>There must be some mechanism which enables the gateways to +reliably identify each other.</em> Without this, they cannot sensibly trust +each other and cannot create a genuinely secure link.</p> + +<p>Any link they do create without some form of <a +href="glossary.html#authentication">authentication</a> will be vulnerable to +a <a href="glossary.html#middle">man-in-the-middle attack</a>. If <a +href="glossary.html#alicebob">Alice and Bob</a> are the people creating the +connection, a villian who can re-route or intercept the packets can pose as +Alice while talking to Bob and pose as Bob while talking to Alice. Alice and +Bob then both talk to the man in the middle, thinking they are talking to +each other, and the villain gets everything sent on the bogus "secure" +connection.</p> + +<p>There are two ways to build links securely, both of which exclude the +man-in-the middle:</p> +<ul> + <li>with <strong>manual keying</strong>, Alice and Bob share a secret key + (which must be transmitted securely, perhaps in a note or via PGP or SSH) + to encrypt their messages. For FreeS/WAN, such keys are stored in the <a + href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> file. Of course, if + an enemy gets the key, all is lost.</li> + <li>with <strong>automatic keying</strong>, the two systems authenticate + each other and negotiate their own secret keys. The keys are + automatically changed periodically.</li> +</ul> + +<p>Automatic keying is much more secure, since if an enemy gets one key only +messages between the previous re-keying and the next are exposed. It is +therefore the usual mode of operation for most IPsec deployment, and the mode +we use in our setup examples. FreeS/WAN does support manual keying for +special circumstanes. See this <a +href="adv_config.html#prodman">section</a>.</p> + +<p>For automatic keying, the two systems must authenticate each other during +the negotiations. There is a choice of methods for this:</p> +<ul> + <li>a <strong>shared secret</strong> provides authentication. If Alice and + Bob are the only ones who know a secret and Alice recives a message which + could not have been created without that secret, then Alice can safely + believe the message came from Bob.</li> + <li>a <a href="glossary.html#public">public key</a> can also provide + authentication. If Alice receives a message signed with Bob's private key + (which of course only he should know) and she has a trustworthy copy of + his public key (so that she can verify the signature), then she can + safely believe the message came from Bob.</li> +</ul> + +<p>Public key techniques are much preferable, for reasons discussed <a +href="config.html#choose">later</a>, and will be used in all our setup +examples. FreeS/WAN does also support auto-keying with shared secret +authentication. See this <a +href="adv_config.html#prodsecrets">section</a>.</p> + +<h2><a name="project">The FreeS/WAN project</a></h2> + +<p>For complete information on the project, see our web site, <a +href="http://liberty.freeswan.org">freeswan.org</a>.</p> + +<p>In summary, we are implementing the <a +href="glossary.html#IPsec">IPsec</a> protocols for Linux and extending them +to do <a href="glossary.html#carpediem">opportunistic encryption</a>.</p> + +<h3><a name="goals">Project goals</a></h3> + +<p>Our overall goal in FreeS/WAN is to make the Internet more secure and more +private.</p> + +<p>Our IPsec implementation supports VPNs and Road Warriors of course. Those +are important applications. Many users will want FreeS/WAN to build corporate +VPNs or to provide secure remote access.</p> + +<p>However, our goals in building it go beyond that. We are trying to help +<strong>build security into the fabric of the Internet</strong> so that +anyone who choses to communicate securely can do so, as easily as they can do +anything else on the net.</p> + +<p>More detailed objectives are:</p> +<ul> + <li>extend IPsec to do <a href="glossary.html#carpediem">opportunistic + encryption</a> so that + <ul> + <li>any two systems can secure their communications without a + pre-arranged connection</li> + <li><strong>secure connections can be the default</strong>, falling + back to unencrypted connections only if: + <ul> + <li><em>both</em> the partner is not set up to co-operate on + securing the connection</li> + <li><em>and</em> your policy allows insecure connections</li> + </ul> + </li> + <li>a significant fraction of all Internet traffic is encrypted</li> + <li>wholesale monitoring of the net (<a + href="politics.html#intro.poli">examples</a>) becomes difficult or + impossible</li> + </ul> + </li> + <li>help make IPsec widespread by providing an implementation with no + restrictions: + <ul> + <li>freely available in source code under the <a + href="glossary.html#GPL">GNU General Public License</a></li> + <li>running on a range of readily available hardware</li> + <li>not subject to US or other nations' <a + href="politics.html#exlaw">export restrictions</a>.<br> + Note that in order to avoid <em>even the appearance</em> of being + subject to those laws, the project cannot accept software + contributions -- <em>not even one-line bug fixes</em> -- from US + residents or citizens.</li> + </ul> + </li> + <li>provide a high-quality IPsec implementation for Linux + <ul> + <li>portable to all CPUs Linux supports: <a + href="compat.html#CPUs">(current list)</a></li> + <li>interoperable with other IPsec implementations: <a + href="interop.html#interop">(current list)</a></li> + </ul> + </li> +</ul> + +<p>If we can get opportunistic encryption implemented and widely deployed, +then it becomes impossible for even huge well-funded agencies to monitor the +net.</p> + +<p>See also our section on <a href="politics.html#politics">history and +politics</a> of cryptography, which includes our project leader's <a +href="politics.html#gilmore">rationale</a> for starting the project.</p> + +<h3><a name="staff">Project team</a></h3> + +<p>Two of the team are from the US and can therefore contribute no code:</p> +<ul> + <li>John Gilmore: founder and policy-maker (<a + href="http://www.toad.com/gnu/">home page</a>)</li> + <li>Hugh Daniel: project manager, Most Demented Tester, and occasionally + Pointy-Haired Boss</li> +</ul> + +<p>The rest of the team are Canadians, working in Canada. (<a +href="politics.html#status">Why Canada?</a>)</p> +<ul> + <li>Hugh Redelmeier: <a href="glossary.html#Pluto">Pluto daemon</a> + programmer</li> + <li>Richard Guy Briggs: <a href="glossary.html#KLIPS">KLIPS</a> + programmer</li> + <li>Michael Richardson: hacker without portfolio</li> + <li>Claudia Schmeing: documentation</li> + <li>Sam Sgro: technical support via the <a href="mail.html#lists">mailing + lists</a></li> +</ul> + +<p>The project is funded by civil libertarians who consider our goals +worthwhile. Most of the team are paid for this work.</p> + +<p>People outside this core team have made substantial contributions. See</p> +<ul> + <li>our <a href="../CREDITS">CREDITS</a> file</li> + <li>the <a href="web.html#patch">patches and add-ons</a> section of our web + references file</li> + <li>lists below of user-written <a href="#howto">HowTos</a> and <a + href="#applied">other papers</a></li> +</ul> + +<p>Additional contributions are welcome. See the <a +href="faq.html#contrib.faq">FAQ</a> for details.</p> + +<h2><a name="products">Products containing FreeS/WAN</a></h2> + +<p>Unfortunately the <a href="politics.html#exlaw">export laws</a> of some +countries restrict the distribution of strong cryptography. FreeS/WAN is +therefore not in the standard Linux kernel and not in all CD or web +distributions.</p> + +<p>FreeS/WAN is, however, quite widely used. Products we know of that use it +are listed below. We would appreciate hearing, via the <a +href="mail.html#lists">mailing lists</a>, of any we don't know of.</p> + +<h3><a name="distwith">Full Linux distributions</a></h3> + +<p>FreeS/WAN is included in various general-purpose Linux distributions, +mostly from countries (shown in brackets) with more sensible laws:</p> +<ul> + <li><a href="http://www.suse.com/">SuSE Linux</a> (Germany)</li> + <li><a href="http://www.conectiva.com">Conectiva</a> (Brazil)</li> + <li><a href="http://www.linux-mandrake.com/en/">Mandrake</a> (France)</li> + <li><a href="http://www.debian.org">Debian</a></li> + <li>the <a href="http://www.pld.org.pl/">Polish(ed) Linux Distribution</a> + (Poland)</li> + <li><a>Best Linux</a> (Finland)</li> +</ul> + +<p>For distributions which do not include FreeS/WAN and are not Redhat (which +we develop and test on), there is additional information in our <a +href="compat.html#otherdist">compatibility</a> section.</p> + +<p>The server edition of <a href="http://www.corel.com">Corel</a> Linux +(Canada) also had FreeS/WAN, but Corel have dropped that product line.</p> + +<h3><a name="kernel_dist">Linux kernel distributions</a></h3> + +<ul> +<li><a href="http://sourceforge.net/projects/wolk/">Working Overloaded Linux Kernel (WOLK)</a></li> +</ul> + + +<h3><a name="office_dist">Office server distributions</a></h3> + +<p>FreeS/WAN is also included in several distributions aimed at the market +for turnkey business servers:</p> +<ul> + <li><a href="http://www.e-smith.com/">e-Smith</a> (Canada), which has + recently been acquired and become the Network Server Solutions group of + <a href="http://www.mitel.com/">Mitel Networks</a> (Canada)</li> + <li><a href="http://www.clarkconnect.org/">ClarkConnect</a> from Point Clark Networks (Canada)</li> + <li><a href="http://www.trustix.net/">Trustix Secure Linux</a> (Norway)</li> + +</ul> + +<h3><a name="fw_dist">Firewall distributions</a></h3> + +<p>Several distributions intended for firewall and router applications +include FreeS/WAN:</p> +<ul> + <li>The <a href="http://www.linuxrouter.org/">Linux Router Project</a> + produces a Linux distribution that will boot from a single floppy. The <a + href="http://leaf.sourceforge.net">LEAF</a> firewall project provides + several different LRP-based firewall packages. At least one of them, + Charles Steinkuehler's Dachstein, includes FreeS/WAN with X.509 + patches.</li> + <li>there are several distributions bootable directly from CD-ROM, usable + on a machine without hard disk. + <ul> + <li>Dachstein (see above) can be used this way</li> + <li><a href="http://www.gibraltar.at/">Gibraltar</a> is based on Debian + GNU/Linux.</li> + <li>at time of writing, <a href="www.xiloo.com">Xiloo</a> is available + only in Chinese. An English version is expected.</li> + </ul> + </li> + <li><a href="http://www.astaro.com/products/index.html">Astaro Security + Linux</a> includes FreeS/WAN. It has some web-based tools for managing + the firewall that include FreeS/WAN configuration management.</li> + <li><a href="http://www.linuxwall.de">Linuxwall</a></li> + <li><a href="http://www.smoothwall.org/">Smoothwall</a></li> + <li><a href="http://www.devil-linux.org/">Devil Linux</a></li> + <li>Coyote Linux has a <a + href="http://embedded.coyotelinux.com/wolverine/index.php">Wolverine</a> + firewall/VPN server</li> +</ul> + +<p>There are also several sets of scripts available for managing a firewall +which is also acting as a FreeS/WAN IPsec gateway. See this <a +href="firewall.html#rules.pub">list</a>.</p> + +<h3><a name="turnkey">Firewall and VPN products</a></h3> + +<p>Several vendors use FreeS/WAN as the IPsec component of a turnkey firewall +or VPN product.</p> + +<p>Software-only products:</p> +<ul> + <li><a href="http://www.linuxmagic.com/vpn/index.html">Linux Magic</a> + offer a VPN/Firewall product using FreeS/WAN</li> + <li>The Software Group's <a + href="http://www.wanware.com/sentinet/">Sentinet</a> product uses + FreeS/WAN</li> + <li><a href="http://www.merilus.com">Merilus</a> use FreeS/WAN in their + Gateway Guardian firewall product</li> +</ul> + +<p>Products that include the hardware:</p> +<ul> + <li>The <a href="http://www.lasat.com">LASAT SafePipe[tm]</a> series. is an + IPsec box based on an embedded MIPS running Linux with FreeS/WAN and a + web-config front end. This company also host our freeswan.org web + site.</li> + <li>Merilus <a + href="http://www.merilus.com/products/fc/index.shtml">Firecard</a> is a + Linux firewall on a PCI card.</li> + <li><a href="http://www.kyzo.com/">Kyzo</a> have a "pizza box" product line + with various types of server, all running from flash. One of them is an + IPsec/PPTP VPN server</li> + <li><a href="http://www.pfn.com">PFN</a> use FreeS/WAN in some of their + products</li> +</ul> + +<p><a href="www.rebel.com">Rebel.com</a>, makers of the Netwinder Linux +machines (ARM or Crusoe based), had a product that used FreeS/WAN. The +company is in receivership so the future of the Netwinder is at best unclear. +<a href="web.html#patch">PKIX patches</a> for FreeS/WAN developed at Rebel +are listed in our web links document.</p> + + +<h2><a name="docs">Information sources</a></h2> + +<h3><a name="docformats">This HowTo, in multiple formats</a></h3> + +<p>FreeS/WAN documentation up to version 1.5 was available only in HTML. Now +we ship two formats:</p> +<ul> + <li>as HTML, one file for each doc section plus a global <a + href="toc.html">Table of Contents</a></li> + <li><a href="HowTo.html">one big HTML file</a> for easy searching</li> +</ul> + +<p>and provide a Makefile to generate other formats if required:</p> +<ul> + <li><a href="HowTo.pdf">PDF</a></li> + <li><a href="HowTo.ps">Postscript</a></li> + <li><a href="HowTo.txt">ASCII text</a></li> +</ul> + +<p>The Makefile assumes the htmldoc tool is available. You can download it +from <a href="http://www.easysw.com">Easy Software</a>.</p> + +<p>All formats should be available at the following websites:</p> +<ul> + <li><a href="http://www.freeswan.org/doc.html">FreeS/WAN project</a></li> + <li><a href="http://www.linuxdoc.org">Linux Documentation Project</a></li> +</ul> + +<p>The distribution tarball has only the two HTML formats.</p> + +<p><strong>Note:</strong> If you need the latest doc version, for example to +see if anyone has managed to set up interoperation between FreeS/WAN and +whatever, then you should download the current snapshot. What is on the web +is documentation as of the last release. Snapshots have all changes I've +checked in to date.</p> + +<h3><a name="rtfm">RTFM (please Read The Fine Manuals)</a></h3> + +<p>As with most things on any Unix-like system, most parts of Linux FreeS/WAN +are documented in online manual pages. We provide a list of <a +href="/mnt/floppy/manpages.html">FreeS/WAN man pages</a>, with links to HTML +versions of them.</p> + +<p>The man pages describing configuration files are:</p> +<ul> + <li><a href="/mnt/floppy/manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a></li> + <li><a + href="/mnt/floppy/manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a></li> +</ul> + +<p>Man pages for common commands include:</p> +<ul> + <li><a href="/mnt/floppy/manpage.d/ipsec.8.html">ipsec(8)</a></li> + <li><a + href="/mnt/floppy/manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</a></li> + <li><a + href="/mnt/floppy/manpage.d/ipsec_newhostkey.8.html">ipsec_newhostkey(8)</a></li> + <li><a href="/mnt/floppy/manpage.d/ipsec_auto.8.html">ipsec_auto(8)</a></li> +</ul> + +<p>You can read these either in HTML using the links above or with the +<var>man(1)</var> command.</p> + +<p>In the event of disagreement between this HTML documentation and the man +pages, the man pages are more likely correct since they are written by the +implementers. Please report any such inconsistency on the <a +href="mail.html#lists">mailing list</a>.</p> + +<h3><a name="text">Other documents in the distribution</a></h3> + +<p>Text files in the main distribution directory are README, INSTALL, +CREDITS, CHANGES, BUGS and COPYING.</p> + +<p>The Libdes encryption library we use has its own documentation. You can +find it in the library directory..</p> + +<h3><a name="assumptions">Background material</a></h3> + +<p>Throughout this documentation, I write as if the reader had at least a +general familiarity with Linux, with Internet Protocol networking, and with +the basic ideas of system and network security. Of course that will certainly +not be true for all readers, and quite likely not even for a majority.</p> + +<p>However, I must limit amount of detail on these topics in the main text. +For one thing, I don't understand all the details of those topics myself. +Even if I did, trying to explain everything here would produce extremely long +and almost completely unreadable documentation.</p> + +<p>If one or more of those areas is unknown territory for you, there are +plenty of other resources you could look at:</p> +<dl> + <dt>Linux</dt> + <dd>the <a href="http://www.linuxdoc.org">Linux Documentation Project</a> + or a local <a href="http://www.linux.org/groups/">Linux User Group</a> + and these <a href="web.html#linux.link">links</a></dd> + <dt>IP networks</dt> + <dd>Rusty Russell's <a + href="http://netfilter.samba.org/unreliable-guides/networking-concepts-HOWTO/index.html">Networking + Concepts HowTo</a> and these <a + href="web.html#IP.background">links</a></dd> + <dt>Security</dt> + <dd>Schneier's book <a href="biblio.html#secrets">Secrets and Lies</a> + and these <a href="web.html#crypto.link">links</a></dd> +</dl> + +<p>Also, I do make an effort to provide some background material in these +documents. All the basic ideas behind IPsec and FreeS/WAN are explained here. +Explanations that do not fit in the main text, or that not everyone will +need, are often in the <a href="glossary.html#ourgloss">glossary</a>, which is +the largest single file in this document set. There is also a <a +href="background.html#background">background</a> file containing various +explanations too long to fit in glossary definitions. All files are heavily +sprinkled with links to each other and to the glossary. <strong>If some passage +makes no sense to you, try the links</strong>.</p> + +<p>For other reference material, see the <a +href="biblio.html#biblio">bibliography</a> and our collection of <a +href="web.html#weblinks">web links</a>.</p> + +<p>Of course, no doubt I get this (and other things) wrong sometimes. +Feedback via the <a href="mail.html#lists">mailing lists</a> is welcome.</p> + +<h3><a name="archives">Archives of the project mailing list</a></h3> + +<p>Until quite recently, there was only one FreeS/WAN mailing list, and +archives of it were:</p> +<ul> + <li><a href="http://www.sandelman.ottawa.on.ca/linux-ipsec">Canada</a></li> + <li><a href="http://www.nexial.com">Holland</a></li> +</ul> +The two archives use completely different search engines. You might want to +try both. + +<p>More recently we have expanded to five lists, each with its own +archive.</p> + +<p><a href="mail.html#lists">More information</a> on mailing lists.</p> + +<h3><a name="howto">User-written HowTo information</a></h3> + +<p>Various user-written HowTo documents are available. The ones covering +FreeS/WAN-to-FreeS/WAN connections are:</p> +<ul> + <li>Jean-Francois Nadeau's <a href="http://jixen.tripod.com/">practical + configurations</a> document</li> + <li>Jens Zerbst's HowTo on <a href="http://dynipsec.tripod.com/">Using + FreeS/WAN with dynamic IP addresses</a>.</li> + <li>an entry in Kurt Seifried's <a + href="http://www.securityportal.com/lskb/kben00000013.html">Linux + Security Knowledge Base</a>.</li> + <li>a section of David Ranch's <a + href="http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#trinityos">Trinity + OS Guide</a></li> + <li>a section in David Bander's book <a href="biblio.html#bander">Linux + Security Toolkit</a></li> +</ul> + +<p>User-wriiten HowTo material may be <strong>especially helpful if you need +to interoperate with another IPsec implementation</strong>. We have neither +the equipment nor the manpower to test such configurations. Users seem to be +doing an admirable job of filling the gaps.</p> +<ul> + <li>list of user-written <a href="interop.html#otherpub">interoperation + HowTos</a> in our interop document</li> +</ul> + +<p>Check what version of FreeS/WAN user-written documents cover. The software +is under active development and the current version may be significantly +different from what an older document describes.</p> + +<h3><a name="applied">Papers on FreeS/WAN</a></h3> + +<p>Two design documents show team thinking on new developments:</p> +<ul> + <li><a href="opportunism.spec">Opportunistic Encryption</a> by technical + lead Henry Spencer and Pluto programmer Hugh Redelemeier</li> + <li>discussion of <a + href="http://www.sandelman.ottawa.on.ca/SSW/freeswan/klips2req/">KLIPS + redesign</a></li> +</ul> + +<p>Both documents are works in progress and are frequently revised. For the +latest version, see the <a href="mail.html#lists">design mailing list</a>. Comments +should go to that list.</p> + +<p>There is now an <a +href="http://www.ietf.org/internet-drafts/draft-richardson-ipsec-opportunistic-06.txt">Internet +Draft on Opportunistic Encryption</a> by Michael Richardson, Hugh Redelmeier +and Henry Spencer. This is a first step toward getting the protocol +standardised so there can be multiple implementations of it. Discussion of it +takes place on the <a +href="http://www.ietf.org/html.charters/ipsec-charter.html">IETF IPsec +Working Group</a> mailing list.</p> + +<p>A number of papers giving further background on FreeS/WAN, or exploring +its future or its applications, are also available:</p> +<ul> + <li>Both Henry and Richard gave talks on FreeS/WAN at the 2000 <a + href="http://www.linuxsymposium.org">Ottawa Linux Symposium</a>. + <ul> + <li>Richard's <a + href="http://www.conscoop.ottawa.on.ca/rgb/freeswan/ols2k/">slides</a></li> + <li>Henry's paper</li> + <li>MP3 audio of their talks is available from the <a + href="http://www.linuxsymposium.org/">conference page</a></li> + </ul> + </li> + <li><cite>Moat: A Virtual Private Network Appliances and Services + Platform</cite> is a paper about large-scale (a few 100 links) use of + FreeS/WAN in a production application at AT&T Research. It is + available in Postscript or PDF from co-author Steve Bellovin's <a + href="http://www.research.att.com/~smb/papers/index.html">papers list + page</a>.</li> + <li>One of the Moat co-authors, John Denker, has also written + <ul> + <li>a <a + href="http://www.av8n.com/vpn/ipsec+routing.htm">proposal</a> + for how future versions of FreeS/WAN might interact with routing + protocols</li> + <li>a <a + href="http://www.av8n.com/vpn/wishlist.htm">wishlist</a> + of possible new features</li> + </ul> + </li> + <li>Bart Trojanowski's web page has a draft design for <a + href="http://www.jukie.net/~bart/linux-ipsec/">hardware acceleration</a> + of FreeS/WAN</li> +</ul> + +<p>Several of these provoked interesting discussions on the mailing lists, +worth searching for in the <a href="mail.html#archive">archives</a>.</p> + +<p>There are also several papers in languages other than English, see our <a +href="web.html#otherlang">web links</a>.</p> + +<h3><a name="licensing">License and copyright information</a></h3> + +<p>All code and documentation written for this project is distributed under +either the GNU General Public License (<a href="glossary.html#GPL">GPL</a>) +or the GNU Library General Public License. For details see the COPYING file +in the distribution.</p> + +<p>Not all code in the distribution is ours, however. See the CREDITS file +for details. In particular, note that the <a +href="glossary.html#LIBDES">Libdes</a> library and the version of <a +href="glossary.html#MD5">MD5</a> that we use each have their own license.</p> + +<h2><a name="sites">Distribution sites</a></h2> + +<p>FreeS/WAN is available from a number of sites.</p> + +<h3>Primary site</h3> + +<p>Our primary site, is at xs4all (Thanks, folks!) in Holland:</p> +<ul> + <li><a href="http://www.xs4all.nl/~freeswan">HTTP</a></li> + <li><a href="ftp://ftp.xs4all.nl/pub/crypto/freeswan">FTP</a></li> +</ul> + +<h3><a name="mirrors">Mirrors</a></h3> + +<p>There are also mirror sites all over the world:</p> +<ul> + <li><a href="http://www.flora.org/freeswan">Eastern Canada</a> (limited + resouces)</li> + <li><a href="ftp://ludwig.doculink.com/pub/freeswan/">Eastern Canada</a> + (has older versions too)</li> + <li><a href="ftp://ntsc.notBSD.org/pub/crypto/freeswan/">Eastern Canada</a> + (has older versions too)</li> + <li><a href="ftp://ftp.kame.net/pub/freeswan/">Japan</a></li> + <li><a href="ftp://ftp.futuredynamics.com/freecrypto/FreeSWAN/">Hong + Kong</a></li> + <li><a href="ftp://ipsec.dk/pub/freeswan/">Denmark</a></li> + <li><a href="ftp://ftp.net.lut.ac.uk/freeswan">the UK</a></li> + <li><a href="http://storm.alert.sk/comp/mirrors/freeswan/">Slovak + Republic</a></li> + <li><a + href="http://the.wiretapped.net/security/vpn-tunnelling/freeswan/">Australia</a></li> + <li><a href="http://freeswan.technolust.cx/">technolust</a></li> + <li><a href="http://freeswan.devguide.de/">Germany</a></li> + <li>Ivan Moore's <a href="http://snowcrash.tdyc.com/freeswan/">site</a></li> + <li>the <a href="http://www.cryptoarchive.net/">Crypto Archive</a> on the + <a href="http://www.securityportal.com/">Security Portal</a> site</li> + <li><a href="http://www.wiretapped.net/">Wiretapped.net</a> in + Australia</li> +</ul> + +<p>Thanks to those folks as well.</p> + +<h3><a name="munitions">The "munitions" archive of Linux crypto +software</a></h3> + +<p>There is also an archive of Linux crypto software called "munitions", with +its own mirrors in a number of countries. It includes FreeS/WAN, though not +always the latest version. Some of its sites are:</p> +<ul> + <li><a href="http://munitions.vipul.net/">Germany</a></li> + <li><a href="http://munitions.iglu.cjb.net/">Italy</a></li> + <li><a href="http://munitions2.xs4all.nl/">Netherlands</a></li> +</ul> + +<p>Any of those will have a list of other "munitions" mirrors. There is also +a CD available.</p> + +<h2>Links to other sections</h2> + +<p>For more detailed background information, see:</p> +<ul> + <li><a href="politics.html#politics">history and politics</a> of + cryptography</li> + <li><a href="ipsec.html#ipsec.detail">IPsec protocols</a></li> +</ul> + +<p>To begin working with FreeS/WAN, go to our <a +href="quickstart.html#quick.guide">quickstart</a> guide.</p> +</body> +</html> diff --git a/doc/src/ipsec.html b/doc/src/ipsec.html new file mode 100644 index 000000000..4647eaf66 --- /dev/null +++ b/doc/src/ipsec.html @@ -0,0 +1,1206 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>IPsec protocols</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, protocol, ESP, AH, IKE"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: ipsec.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="ipsec.detail">The IPsec protocols</a></h1> + +<p>This section provides information on the IPsec protocols which FreeS/WAN +implements. For more detail, see the <a href="rfc.html">RFCs</a>.</p> + +<p>The basic idea of IPsec is to provide security functions, <a +href="glossary.html#authentication">authentication</a> and <a +href="glossary.html#encryption">encryption</a>, at the IP (Internet Protocol) +level. This requires a higher-level protocol (IKE) to set things up for the +IP-level services (ESP and AH).</p> + +<h2>Protocols and phases</h2> + +<p>Three protocols are used in an IPsec implementation:</p> +<dl> + <dt>ESP, Encapsulating Security Payload</dt> + <dd>Encrypts and/or authenticates data</dd> + <dt>AH, Authentication Header</dt> + <dd>Provides a packet authentication service</dd> + <dt>IKE, Internet Key Exchange</dt> + <dd>Negotiates connection parameters, including keys, for the other + two</dd> +</dl> + +<p>The term "IPsec" (also written as IPSEC) is slightly ambiguous. In some +contexts, it includes all three of the above but in other contexts it refers +only to AH and ESP.</p> + +<p>There is more detail below, but a quick summary of how the whole thing +works is:</p> +<dl> + <dt>Phase one IKE (main mode exchange)</dt> + <dd>sets up a keying channel (ISAKMP SA) between the two gateways</dd> + <dt>Phase two IKE (quick mode exchange)</dt> + <dd>sets up data channels (IPsec SAs)</dd> + <dt>IPsec proper</dt> + <dd>exchanges data using AH or ESP</dd> +</dl> + +<p>Both phases of IKE are repeated periodically to automate re-keying.</p> + +<h2><a name="others">Applying IPsec</a></h2> + +<p>Authentication and encryption functions for network data can, of course, +be provided at other levels. Many security protocols work at levels above +IP.</p> +<ul> + <li><a href="glossary.html#PGP">PGP</a> encrypts and authenticates mail + messages</li> + <li><a href="glossary.html#SSH">SSH</a> authenticates remote logins and + then encrypts the session</li> + <li><a href="glossary.html#SSL">SSL</a> or <a + href="glossary.html#TLS">TLS</a> provides security at the sockets layer, + e.g. for secure web browsing</li> +</ul> + +<p>and so on. Other techniques work at levels below IP. For example, data on +a communications circuit or an entire network can be encrypted by specialised +hardware. This is common practice in high-security applications.</p> + +<h3><a name="advantages">Advantages of IPsec</a></h3> + +<p>There are, however, advantages to doing it at the IP level instead of, or +as well as, at other levels.</p> + +<p>IPsec is the <strong>most general way to provide these services for the +Internet</strong>.</p> +<ul> + <li>Higher-level services protect a <em>single protocol</em>; for example + PGP protects mail.</li> + <li>Lower level services protect a <em>single medium</em>; for example a + pair of encryption boxes on the ends of a line make wiretaps on that line + useless unless the attacker is capable of breaking the encryption.</li> +</ul> + +<p>IPsec, however, can protect <em>any protocol</em> running above IP and +<em>any medium</em> which IP runs over. More to the point, it can protect a +mixture of application protocols running over a complex combination of media. +This is the normal situation for Internet communication; IPsec is the only +general solution.</p> + +<p>IPsec can also provide some security services "in the background", with +<strong>no visible impact on users</strong>. To use <a +href="glossary.html#PGP">PGP</a> encryption and signatures on mail, for +example, the user must at least:</p> +<ul> + <li>remember his or her passphrase,</li> + <li>keep it secure</li> + <li>follow procedures to validate correspondents' keys</li> +</ul> + +<p>These systems can be designed so that the burden on users is not onerous, +but any system will place some requirements on users. No such system can hope +to be secure if users are sloppy about meeting those requirements. The author +has seen username and password stuck on terminals with post-it notes in an +allegedly secure environment, for example.</p> + +<h3><a name="limitations">Limitations of IPsec</a></h3> + +<p>IPsec is designed to secure IP links between machines. It does that well, +but it is important to remember that there are many things it does not do. +Some of the important limitations are:</p> +<dl> + <dt><a name="depends">IPsec cannot be secure if your system isn't</a></dt> + <dd>System security on IPsec gateway machines is an essential requirement + if IPsec is to function as designed. No system can be trusted if the + underlying machine has been subverted. See books on Unix security such + as <a href="biblio.html#practical">Garfinkel and Spafford</a> or our + web references for <a href="web.html#linsec">Linux security</a> or more + general <a href="web.html#compsec">computer security</a>. + <p>Of course, there is another side to this. IPsec can be a powerful + tool for improving system and network security. For example, requiring + packet authentication makes various spoofing attacks harder and IPsec + tunnels can be extremely useful for secure remote administration of + various things.</p> + </dd> + <dt><a name="not-end-to-end">IPsec is not end-to-end</a></dt> + <dd>IPsec cannot provide the same end-to-end security as systems working + at higher levels. IPsec encrypts an IP connection between two machines, + which is quite a different thing than encrypting messages between users + or between applications. + <p>For example, if you need mail encrypted from the sender's desktop to + the recipient's desktop and decryptable only by the recipient, use <a + href="glossary.html#PGP">PGP</a> or another such system. IPsec can + encrypt any or all of the links involved -- between the two mail + servers, or between either server and its clients. It could even be + used to secure a direct IP link from the sender's desktop machine to + the recipient's, cutting out any sort of network snoop. What it cannot + ensure is end-to-end user-to-user security. If only IPsec is used to + secure mail, then anyone with appropriate privileges on any machine + where that mail is stored (at either end or on any store-and-forward + servers in the path) can read it.</p> + <p>In another common setup, IPsec encrypts packets at a security + gateway machine as they leave the sender's site and decrypts them on + arrival at the gateway to the recipient's site. This does provide a + useful security service -- only encrypted data is passed over the + Internet -- but it does not even come close to providing an end-to-end + service. In particular, anyone with appropriate privileges on either + site's LAN can intercept the message in unencrypted form.</p> + </dd> + <dt><a name="notpanacea">IPsec cannot do everything</a></dt> + <dd>IPsec also cannot provide all the functions of systems working at + higher levels of the protocol stack. If you need a document + electronically signed by a particular person, then you need his or her + <a href="glossary.html#signature">digital signature</a> and a <a + href="glossary.html#public">public key cryptosystem</a> to verify it + with. + <p>Note, however, that IPsec authentication of the underlying + communication can make various attacks on higher-level protocols more + difficult. In particular, authentication prevents <a + href="glossary.html#middle">man-in-the-middle attacks</a>.</p> + </dd> + <dt><a name="no_user">IPsec authenticates machines, not users</a></dt> + <dd>IPsec uses strong authentication mechanisms to control which messages + go to which machines, but it does not have the concept of user ID, + which is vital to many other security mechansims and policies. This + means some care must be taken in fitting the various security + mechansims on a network together. For example, if you need to control + which users access your database server, you need some non-IPsec + mechansim for that. IPsec can control which machines connect to the + server, and can ensure that data transfer to those machines is done + securely, but that is all. Either the machines themselves must control + user access or there must be some form of user authentication to the + database, independent of IPsec.</dd> + <dt><a name="DoS">IPsec does not stop denial of service attacks</a></dt> + <dd><a href="glossary.html#DOS">Denial of service</a> attacks aim at + causing a system to crash, overload, or become confused so that + legitimate users cannot get whatever services the system is supposed to + provide. These are quite different from attacks in which the attacker + seeks either to use the service himself or to subvert the service into + delivering incorrect results. + <p>IPsec shifts the ground for DoS attacks; the attacks possible + against systems using IPsec are different than those that might be used + against other systems. It does not, however, eliminate the possibility + of such attacks.</p> + </dd> + <dt><a name="traffic">IPsec does not stop traffic analysis</a></dt> + <dd><a href="glossary.html#traffic">Traffic analysis</a> is the attempt + to derive intelligence from messages without regard for their contents. + In the case of IPsec, it would mean analysis based on things visible in + the unencrypted headers of encrypted packets -- source and destination + gateway addresses, packet size, et cetera. Given the resources to + acquire such data and some skill in analysing it (both of which any + national intelligence agency should have), this can be a very powerful + technique. + <p>IPsec is not designed to defend against this. Partial defenses are + certainly possible, and some are <a href="#traffic.resist">described + below</a>, but it is not clear that any complete defense can be + provided.</p> + </dd> +</dl> + +<h3><a name="uses">IPsec is a general mechanism for securing IP</a></h3> + +<p>While IPsec does not provide all functions of a mail encryption package, +it can encrypt your mail. In particular, it can ensure that all mail passing +between a pair or a group of sites is encrypted. An attacker looking only at +external traffic, without access to anything on or behind the IPsec gateway, +cannot read your mail. He or she is stymied by IPsec just as he or she would +be by <a href="glossary.html#PGP">PGP</a>.</p> + +<p>The advantage is that IPsec can provide the same protection for <strong> +anything transmitted over IP</strong>. In a corporate network example, PGP +lets the branch offices exchange secure mail with head office. SSL and SSH +allow them to securely view web pages, connect as terminals to machines, and +so on. IPsec can support all those applications, plus database queries, file +sharing (NFS or Windows), other protocols encapsulated in IP (Netware, +Appletalk, ...), phone-over-IP, video-over-IP, ... anything-over-IP. The only +limitation is that IP Multicast is not yet supported, though there are +Internet Draft documents for that.</p> + +<p>IPsec creates <strong>secure tunnels through untrusted networks</strong>. +Sites connected by these tunnels form VPNs, <a +href="glossary.html#VPN">Virtual Private Networks</a>.</p> + +<p>IPsec gateways can be installed wherever they are required.</p> +<ul> + <li>One organisation might choose to install IPsec only on firewalls + between their LANs and the Internet. This would allow them to create a + VPN linking several offices. It would provide protection against anyone + outside their sites.</li> + <li>Another might install IPsec on departmental servers so everything on + the corporate backbone net was encrypted. This would protect messages on + that net from everyone except the sending and receiving department.</li> + <li>Another might be less concerned with information secrecy and more with + controlling access to certain resources. They might use IPsec packet + authentication as part of an access control mechanism, with or without + also using the IPsec encryption service.</li> + <li>It is even possible (assuming adequate processing power and an IPsec + implementation in each node) to make every machine its own IPsec gateway + so that everything on a LAN is encrypted. This protects information from + everyone outside the sending and receiving machine.</li> + <li>These techniques can be combined in various ways. One might, for + example, require authentication everywhere on a network while using + encryption only for a few links.</li> +</ul> + +<p>Which of these, or of the many other possible variants, to use is up to +you. <strong>IPsec provides mechanisms; you provide the policy</strong>.</p> + +<p><strong>No end user action is required</strong> for IPsec security to be +used; they don't even have to know about it. The site administrators, of +course, do have to know about it and to put some effort into making it work. +Poor administration can compromise IPsec as badly as the post-it notes +mentioned above. It seems reasonable, though, for organisations to hope their +system administrators are generally both more security-conscious than end +users and more able to follow computer security procedures. If not, at least +there are fewer of them to educate or replace.</p> + +<p>IPsec can be, and often should be, used with along with security protocols +at other levels. If two sites communicate with each other via the Internet, +then IPsec is the obvious way to protect that communication. If two others +have a direct link between them, either link encryption or IPsec would make +sense. Choose one or use both. Whatever you use at and below the IP level, +use other things as required above that level. Whatever you use above the IP +level, consider what can be done with IPsec to make attacks on the higher +levels harder. For example, <a href="glossary.html#middle">man-in-the-middle +attacks</a> on various protocols become difficult if authentication at packet +level is in use on the potential victims' communication channel.</p> + +<h3><a name="authonly">Using authentication without encryption</a></h3> + +<p>Where appropriate, IPsec can provide authentication without encryption. +One might do this, for example:</p> +<ul> + <li>where the data is public but one wants to be sure of getting the right + data, for example on some web sites</li> + <li>where encryption is judged unnecessary, for example on some company or + department LANs</li> + <li>where strong encryption is provided at link level, below IP</li> + <li>where strong encryption is provided in other protocols, above IP<br> + Note that IPsec authentication may make some attacks on those protocols + harder.</li> +</ul> + +<p>Authentication has lower overheads than encryption.</p> + +<p>The protocols provide four ways to build such connections, using either an +AH-only connection or ESP using null encryption, and in either manually or +automatically keyed mode. FreeS/WAN supports only one of these, manually +keyed AH-only connections, and <strong>we do not recommend using +that</strong>. Our reasons are discussed under <a +href="#traffic.resist">Resisting traffic analysis</a> a few sections further +along.</p> + +<h3><a name="encnoauth">Encryption without authentication is +dangerous</a></h3> + +<p>Originally, the IPsec encryption protocol <a +href="glossary.html#ESP">ESP</a> didn't do integrity checking. It only did +encryption. Steve Bellovin found many ways to attack ESP used without +authentication. See his paper <a +href="http://www.research.att.com/~smb/papers/badesp.ps">Problem areas for +the IP Security Protocols</a>. To make a secure connection, you had to add an +<a href="glossary.html#AH">AH</a> Authentication Header as well as ESP. +Rather than incur the overhead of several layers (and rather than provide an +ESP layer that didn't actually protect the traffic), the IPsec working group +built integrity and replay checking directly into ESP.</p> + +<p>Today, typical usage is one of:</p> +<ul> + <li>ESP for encryption and authentication</li> + <li>AH for authentication alone</li> +</ul> + +<p>Other variants are allowed by the standard, but not much used:</p> +<dl> + <dt>ESP encryption without authentication</dt> + <dd><strong>Bellovin has demonstrated fatal flaws in this. Do not + use.</strong></dd> + <dt>ESP encryption with AH authentication</dt> + <dd>This has higher overheads than using the authentication in ESP, and + no obvious benefit in most cases. The exception might be a network + where AH authentication was widely or universally used. If you're going + to do AH to conform with network policy, why authenticate again in the + ESP layer?</dd> + <dt>Authenticate twice, with AH and with ESP</dt> + <dd>Why? Of course, some folk consider "belt and suspenders" the sensible + approach to security. If you're among them, you might use both + protocols here. You might also use both to satisfy different parts of a + security policy. For example, an organisation might require AH + authentication everywhere but two users within the organisation might + use ESP as well.</dd> + <dt>ESP authentication without encryption</dt> + <dd>The standard allows this, calling it "null encryption". FreeS/WAN + does not support it. We recommend that you use AH instead if + authentication is all you require. AH authenticates parts of the IP + header, which ESP-null does not do.</dd> +</dl> + +<p>Some of these variants cannot be used with FreeS/WAN because we do not +support ESP-null and do not support automatic keying of AH-only +connections.</p> + +<p>There are fairly frequent suggestions that AH be dropped entirely from the +IPsec specifications since ESP and null encryption can handle that situation. +It is not clear whether this will occur. My guess is that it is unlikely.</p> + +<h3><a name="multilayer">Multiple layers of IPsec processing are +possible</a></h3> + +<p>The above describes combinations possible on a single IPsec connection. In +a complex network you may have several layers of IPsec in play, with any of +the above combinations at each layer.</p> + +<p>For example, a connection from a desktop machine to a database server +might require AH authentication. Working with other host, network and +database security measures, AH might be just the thing for access control. +You might decide not to use ESP encryption on such packets, since it uses +resources and might complicate network debugging. Within the site where the +server is, then, only AH would be used on those packets.</p> + +<p>Users at another office, however, might have their whole connection (AH +headers and all) passing over an IPsec tunnel connecting their office to the +one with the database server. Such a tunnel should use ESP encryption and +authentication. You need authentication in this layer because without +authentication the encryption is vulnerable and the gateway cannot verify the +AH authentication. The AH is between client and database server; the gateways +aren't party to it.</p> + +<p>In this situation, some packets would get multiple layers of IPsec applied +to them, AH on an end-to-end client-to-server basis and ESP from one office's +security gateway to the other.</p> + +<h3><a name="traffic.resist">Resisting traffic analysis</a></h3> + +<p><a href="glossary.html#traffic">Traffic analysis</a> is the attempt to +derive useful intelligence from encrypted traffic without breaking the +encryption.</p> + +<p>Is your CEO exchanging email with a venture capital firm? With bankruptcy +trustees? With an executive recruiting agency? With the holder of some +important patents? If an eavesdropper learns about any of those, then he has +interesting intelligence on your company, whether or not he can read the +messages themselves.</p> + +<p>Even just knowing that there is network traffic between two sites may tell +an analyst something useful, especially when combined with whatever other +information he or she may have. For example, if you know Company A is having +cashflow problems and Company B is looking for aquisitions, then knowing that +packets are passing between the two is interesting. It is more interesting if +you can tell it is email, and perhaps yet more if you know the sender and +recipient.</p> + +<p>Except in the simplest cases, traffic analysis is hard to do well. It +requires both considerable resources and considerable analytic skill. +However, intelligence agencies of various nations have been doing it for +centuries and many of them are likely quite good at it by now. Various +commercial organisations, especially those working on "targeted marketing" +may also be quite good at analysing certain types of traffic.</p> + +<p>In general, defending against traffic analysis is also difficult. +Inventing a really good defense could get you a PhD and some interesting job +offers.</p> + +<p>IPsec is not designed to stop traffic analysis and we know of no plausible +method of extending it to do so. That said, there are ways to make traffic +analysis harder. This section describes them.</p> + +<h4><a name="extra">Using "unnecessary" encryption</a></h4> + +<p>One might choose to use encryption even where it appears unnecessary in +order to make analysis more difficult. Consider two offices which pass a +small volume of business data between them using IPsec and also transfer +large volumes of Usenet news. At first glance, it would seem silly to encrypt +the newsfeed, except possibly for any newsgroups that are internal to the +company. Why encrypt data that is all publicly available from many sites?</p> + +<p>However, if we encrypt a lot of news and send it down the same connection +as our business data, we make <a href="glossary.html#traffic">traffic +analysis</a> much harder. A snoop cannot now make inferences based on +patterns in the volume, direction, sizes, sender, destination, or timing of +our business messages. Those messages are hidden in a mass of news messages +encapsulated in the same way.</p> + +<p>If we're going to do this we need to ensure that keys change often enough +to remain secure even with high volumes and with the adversary able to get +plaintext of much of the data. We also need to look at other attacks this +might open up. For example, can the adversary use a chosen plaintext attack, +deliberately posting news articles which, when we receive and encrypt them, +will help break our encryption? Or can he block our business data +transmission by flooding us with silly news articles? Or ...</p> + +<p>Also, note that this does not provide complete protection against traffic +analysis. A clever adversary might still deduce useful intelligence from +statistical analysis (perhaps comparing the input newsfeed to encrypted +output, or comparing the streams we send to different branch offices), or by +looking for small packets which might indicate establishment of TCP +connections, or ...</p> + +<p>As a general rule, though, to improve resistance to traffic analysis, you +should <strong>encrypt as much traffic as possible, not just as much as seems +necessary.</strong></p> + +<h4><a name="multi-encrypt">Using multiple encryption</a></h4> + +<p>This also applies to using multiple layers of encryption. If you have an +IPsec tunnel between two branch offices, it might appear silly to send <a +href="glossary.html#PGP">PGP</a>-encrypted email through that tunnel. +However, if you suspect someone is snooping your traffic, then it does make +sense:</p> +<ul> + <li>it protects the mail headers; they cannot even see who is mailing + who</li> + <li>it protects against user bungles or software malfunctions that + accidentally send messages in the clear</li> + <li>it makes any attack on the mail encryption much harder; they have to + break IPsec or break into your network before they can start on the mail + encryption</li> +</ul> + +<p>Similar arguments apply for <a href="glossary.html#SSL">SSL</a>-encrypted +web traffic or <a href="glossary.html#SSH">SSH</a>-encrypted remote login +sessions, even for end-to-end IPsec tunnels between systems in the two +offices.</p> + +<h4><a name="fewer">Using fewer tunnels</a></h4> + +<p>It may also help to use fewer tunnels. For example, if all you actually +need encrypted is connections between:</p> +<ul> + <li>mail servers at branch and head offices</li> + <li>a few branch office users and the head office database server</li> +</ul> + +<p>You might build one tunnel per mail server and one per remote database +user, restricting traffic to those applications. This gives the traffic +analyst some information, however. He or she can distinguish the tunnels by +looking at information in the ESP header and, given that distinction and the +patterns of tunnel usage, might be able to figure out something useful. +Perhaps not, but why take the risk?</p> + +<p>We suggest instead that you build one tunnel per branch office, encrypting +everything passing from head office to branches. This has a number of +advantages:</p> +<ul> + <li>it is easier to build and administer</li> + <li>it resists traffic analysis somewhat better</li> + <li>it provides security for whatever you forgot. For example, if some user + at a remote office browses proprietary company data on some head office + web page (that the security people may not even know about!), then that + data is encrypted before it reaches the Internet.</li> +</ul> + +<p>Of course you might also want to add additional tunnels. For example, if +some of the database data is confidential and should not be exposed even +within the company, then you need protection from the user's desktop to the +database server. We suggest you do that in whatever way seems appropriate -- +IPsec, SSH or SSL might fit -- but, whatever you choose, pass it between +locations via a gateway-to-gateway IPsec tunnel to provide some resistance to +traffic analysis.</p> + +<h2><a name="primitives">Cryptographic components</a></h2> + +<p>IPsec combines a number of cryptographic techniques, all of them +well-known and well-analyzed. The overall design approach was conservative; +no new or poorly-understood components were included.</p> + +<p>This section gives a brief overview of each technique. It is intended only +as an introduction. There is more information, and links to related topics, +in our <a href="glossary.html">glossary</a>. See also our <a +href="biblio.html">bibliography</a> and cryptography <a +href="web.html#crypto.link">web links</a>.</p> + +<h3><a name="block.cipher">Block ciphers</a></h3> + +<p>The <a href="glossary.html#encryption">encryption</a> in the <a +href="glossary.html#ESP">ESP</a> encapsulation protocol is done with a <a +href="glossary.html#block">block cipher</a>.</p> + +<p>We do not implement <a href="glossary.html#DES">single DES</a>. It is <a +href="politics.html#desnotsecure">insecure</a>. Our default, and currently +only, block cipher is <a href="glossary.html#3DES">triple DES</a>.</p> + +<p>The <a href="glossary.html#rijndael">Rijndael</a> block cipher has won the +<a href="glossary.html#AES">AES</a> competition to choose a relacement for +DES. It will almost certainly be added to FreeS/WAN and to other IPsec +implementations. <a href="web.html#patch">Patches</a> are already +available.</p> + +<h3><a name="hash.ipsec">Hash functions</a></h3> + +<h4><a name="hmac.ipsec">The HMAC construct</a></h4> + +<p>IPsec packet authentication is done with the <a +href="glossary.html#HMAC">HMAC</a> construct. This is not just a hash of the +packet data, but a more complex operation which uses both a hashing algorithm +and a key. It therefore does more than a simple hash would. A simple hash +would only tell you that the packet data was not changed in transit, or that +whoever changed it also regenerated the hash. An HMAC also tells you that the +sender knew the HMAC key.</p> + +<p>For IPsec HMAC, the output of the hash algorithm is truncated to 96 bits. +This saves some space in the packets. More important, it prevents an attacker +from seeing all the hash output bits and perhaps creating some sort of attack +based on that knowledge.</p> + +<h4>Choice of hash algorithm</h4> + +<p>The IPsec RFCs require two hash algorithms -- <a +href="glossary.html#MD5">MD5</a> and <a href="glossary.html#SHA">SHA-1</a> -- +both of which FreeS/WAN implements.</p> + +<p>Various other algorithms -- such as RIPEMD and Tiger -- are listed in the +RFCs as optional. None of these are in the FreeS/WAN distribution, or are +likely to be added, although user <a href="web.html#patch">patches</a> exist +for several of them.</p> + +<p>Additional hash algorithms -- <a href="glossary.html#SHA-256">SHA-256, +SHA-384 and SHA-512</a> -- may be required to give hash strength matching the +strength of <a href="glossary.html#AES">AES</a>. These are likely to be added +to FreeS/WAN along with AES.</p> + +<h3><a name="DH.keying">Diffie-Hellman key agreement</a></h3> + +<p>The <a href="glossary.html#DH">Diffie-Hellman</a> key agreement protocol +allows two parties (A and B or <a href="glossary.html#alicebob">Alice and +Bob</a>) to agree on a key in such a way that an eavesdropper who intercepts +the entire conversation cannot learn the key.</p> + +<p>The protocol is based on the <a href="glossary.html#dlog">discrete +logarithm</a> problem and is therefore thought to be secure. Mathematicians +have been working on that problem for years and seem no closer to a solution, +though there is no proof that an efficient solution is impossible.</p> + +<h3><a name="RSA.auth">RSA authentication</a></h3> + +<p>The <a href="glossary.html#RSA">RSA</a> algorithm (named for its inventors +-- Rivest, Shamir and Adleman) is a very widely used <a +href="glossary.html#">public key</a> cryptographic technique. It is used in +IPsec as one method of authenticating gateways for Diffie-Hellman key +negotiation.</p> + +<h2><a name="structure">Structure of IPsec</a></h2> + +<p>There are three protocols used in an IPsec implementation:</p> +<dl> + <dt>ESP, Encapsulating Security Payload</dt> + <dd>Encrypts and/or authenticates data</dd> + <dt>AH, Authentication Header</dt> + <dd>Provides a packet authentication service</dd> + <dt>IKE, Internet Key Exchange</dt> + <dd>Negotiates connection parameters, including keys, for the other + two</dd> +</dl> + +<p>The term "IPsec" is slightly ambiguous. In some contexts, it includes all +three of the above but in other contexts it refers only to AH and ESP.</p> + +<h3><a name="IKE.ipsec">IKE (Internet Key Exchange)</a></h3> + +<p>The IKE protocol sets up IPsec (ESP or AH) connections after negotiating +appropriate parameters (algorithms to be used, keys, connection lifetimes) +for them. This is done by exchanging packets on UDP port 500 between the two +gateways.</p> + +<p>IKE (RFC 2409) was the outcome of a long, complex process in which quite a +number of protocols were proposed and debated. Oversimplifying mildly, IKE +combines:</p> +<dl> + <dt>ISAKMP (RFC 2408)</dt> + <dd>The <strong>I</strong>nternet <strong>S</strong>ecurity + <strong>A</strong>ssociation and <strong>K</strong>ey + <strong>M</strong>anagement <strong>P</strong>rotocol manages + negotiation of connections and defines <a + href="glossary.html#SA">SA</a>s (Security Associations) as a means of + describing connection properties.</dd> + <dt>IPsec DOI for ISAKMP (RFC 2407)</dt> + <dd>A <strong>D</strong>omain <strong>O</strong>f + <strong>I</strong>nterpretation fills in the details necessary to turn + the rather abstract ISAKMP protocol into a more tightly specified + protocol, so it becomes applicable in a particular domain.</dd> + <dt>Oakley key determination protocol (RFC 2412)</dt> + <dd>Oakley creates keys using the <a + href="glossary.html#DH">Diffie-Hellman</a> key agreement protocol.</dd> +</dl> + +<p>For all the details, you would need to read the four <a +href="rfc.html">RFCs</a> just mentioned (over 200 pages) and a number of +others. We give a summary below, but it is far from complete.</p> + +<h4><a name="phases">Phases of IKE</a></h4> + +<p>IKE negotiations have two phases.</p> +<dl> + <dt>Phase one</dt> + <dd>The two gateways negotiate and set up a two-way ISAKMP SA which they + can then use to handle phase two negotiations. One such SA between a + pair of gateways can handle negotiations for multiple tunnels.</dd> + <dt>Phase two</dt> + <dd>Using the ISAKMP SA, the gateways negotiate IPsec (ESP and/or AH) SAs + as required. IPsec SAs are unidirectional (a different key is used in + each direction) and are always negotiated in pairs to handle two-way + traffic. There may be more than one pair defined between two + gateways.</dd> +</dl> + +<p>Both of these phases use the UDP protocol and port 500 for their +negotiations.</p> + +<p>After both IKE phases are complete, you have IPsec SAs to carry your +encrypted data. These use the ESP or AH protocols. These protocols do not +have ports. Ports apply only to UDP or TCP.</p> + +<p>The IKE protocol is designed to be extremely flexible. Among the things +that can be negotiated (separately for each SA) are:</p> +<ul> + <li>SA lifetime before rekeying</li> + <li>encryption algorithm used. We currently support only <a + href="glossary.html#3DES">triple DES</a>. Single DES is <a + href="politics.html#desnotsecure">insecure</a>. The RFCs say you MUST do + DES, SHOULD do 3DES and MAY do various others. We do not do any of the + others.</li> + <li>authentication algorithms. We support <a + href="glossary.html#MD5">MD5</a> and <a href="glossary.html#SHA">SHA</a>. + These are the two the RFCs require.</li> + <li>choice of group for <a href="glossary.html#DH">Diffie-Hellman</a> key + agreement. We currently support Groups 2 and 5 (which are defined modulo + primes of various lengths) and do not support Group 1 (defined modulo a + shorter prime, and therefore cryptographically weak) or groups 3 and 4 + (defined using elliptic curves). The RFCs require only Group 1.</li> +</ul> + +<p>The protocol also allows implementations to add their own encryption +algorithms, authentication algorithms or Diffie-Hellman groups. We do not +support any such extensions, but there are some <a +href="web.html#patch">patches</a> that do.</p> + +<p>There are a number of complications:</p> +<ul> + <li>The gateways must be able to authenticate each other's identities + before they can create a secure connection. This host authentication is + part of phase one negotiations, and is a required prerequisite for packet + authentication used later. Host authentication can be done in a variety + of ways. Those supported by FreeS/WAN are discussed in our <a + href="adv_config.html#auto-auth">advanced configuration</a> document.</li> + <li>Phase one can be done in two ways. + <ul> + <li>Main Mode is required by the RFCs and supported in FreeS/WAN. It + uses a 6-packet exzchange.</li> + <li>Aggressive Mode is somewhat faster (only 3 packets) but reveals + more to an eavesdropper. This is optional in the RFCs, not currently + supported by FreeS/WAN, and not likely to be.</li> + </ul> + </li> + <li>A new group exchange may take place after phase one but before phase + two, defining an additional group for use in the <a + href="glossary.html#DH">Diffie-Hellman</a> key agreement part of phase + two. FreeS/WAN does not currently support this.</li> + <li>Phase two always uses Quick Mode, but there are two variants of that: + <ul> + <li>One variant provides <a href="glossary.html#PFS">Perfect Forward + Secrecy (PFS)</a>. An attacker that obtains your long-term host + authentication key does not immediately get any of your short-term + packet encryption of packet authentication keys. He must conduct + another successful attack each time you rekey to get the short-term + keys. Having some short-term keys does not help him learn others. In + particular, breaking your system today does not let him read messages + he archived yestarday, assuming you've changed short-term keys in the + meanwhile. We enable PFS as the default.</li> + <li>The other variant disables PFS and is therefore slightly faster. We + do not recommend this since it is less secure, but FreeS/WAN does + support it. You can enable it with a <var>pfs=no</var> statement in + <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>.</li> + <li>The protocol provides no way to negotiate which variant will be + used. If one gateway is set for PFS and the other is not, the + negotiation fails. This has proved a fairly common source of + interoperation problems.</li> + </ul> + </li> + <li>Several types of notification message may be sent by either side during + either phase, or later. FreeS/WAN does not currently support these, but + they are a likely addition in future releases.</li> + <li>There is a commit flag which may optionally be set on some messages. + The <a href="http://www.lounge.org/ike_doi_errata.html">errata</a> page + for the RFCs includes two changes related to this, one to clarify the + description of its use and one to block a <a + href="glossary.html#DOS">denial of service</a> attack which uses it. We + currently do not implement this feature.</li> +</ul> + +<p>These complications can of course lead to problems, particularly when two +different implementations attempt to interoperate. For example, we have seen +problems such as:</p> +<ul> + <li>Some implementations (often products crippled by <a + href="politics.html#exlaw">export laws</a>) have the insecure DES + algorithm as their only supported encryption method. Other parts of our + documentation discuss the <a + href="politics.html#desnotsecure">reasons we do not implement single + DES</a>, and <a href="interop.html#noDES">how to cope with crippled + products</a>.</li> + <li>Windows 2000 IPsec tries to negotiate using Aggressive Mode, which we + don't support. Later on, it uses the commit bit, which we also don't + support.</li> + <li>Various implementations disable PFS by default, and therefore will not + talk to FreeS/WAN until you either turn on PFS on their end or turn it + off in FreeS/WAN with a <var>pfs=no</var> entry in the connection + description.</li> + <li>FreeS/WAN's interaction with PGPnet is complicated by their use of + notification messages we do not yet support.</li> +</ul> + +<p>Despite this, we do interoperate successfully with many implementations, +including both Windows 2000 and PGPnet. Details are in our <a +href="interop.html">interoperability</a> document.</p> + +<h4><a name="sequence">Sequence of messages in IKE</a></h4> + +<p>Each phase (see <a href="#phases">previous section</a>)of IKE involves a +series of messages. In Pluto error messages, these are abbreviated using:</p> +<dl> + <dt>M</dt> + <dd><strong>M</strong>ain mode, settting up the keying channel (ISAKMP + SA)</dd> + <dt>Q</dt> + <dd><strong>Q</strong>uick mode, setting up the data channel (IPsec + SA)</dd> + <dt>I</dt> + <dd><strong>I</strong>nitiator, the machine that starts the + negotiation</dd> + <dt>R</dt> + <dd><strong>R</strong>esponder</dd> +</dl> + +<p>For example, the six messages of a main mode negotiation, in sequence, are +labelled:</p> +<pre> MI1 ----------> + <---------- MR1 + MI2 ----------> + <---------- MR2 + MI3 ----------> + <---------- MR3</pre> + +<h4><a name="struct.exchange">Structure of IKE messages</a></h4> + +<p>Here is our Pluto developer explaining some of this on the mailing +list:</p> +<pre>When one IKE system (for example, Pluto) is negotiating with another +to create an SA, the Initiator proposes a bunch of choices and the +Responder replies with one that it has selected. + +The structure of the choices is fairly complicated. An SA payload +contains a list of lists of "Proposals". The outer list is a set of +choices: the selection must be from one element of this list. + +Each of these elements is a list of Proposals. A selection must be +made from each of the elements of the inner list. In other words, +*all* of them apply (that is how, for example, both AH and ESP can +apply at once). + +Within each of these Proposals is a list of Transforms. For each +Proposal selected, one Transform must be selected (in other words, +each Proposal provides a choice of Transforms). + +Each Transform is made up of a list of Attributes describing, well, +attributes. Such as lifetime of the SA. Such as algorithm to be +used. All the Attributes apply to a Transform. + +You will have noticed a pattern here: layers alternate between being +disjunctions ("or") and conjunctions ("and"). + +For Phase 1 / Main Mode (negotiating an ISAKMP SA), this structure is +cut back. There must be exactly one Proposal. So this degenerates to +a list of Transforms, one of which must be chosen.</pre> + +<h3><a name="services">IPsec Services, AH and ESP</a></h3> + +<p>IPsec offers two services, <a +href="glossary.html#authentication">authentication</a> and <a +href="glossary.html#encryption">encryption</a>. These can be used separately +but are often used together.</p> +<dl> + <dt>Authentication</dt> + <dd>Packet-level authentication allows you to be confident that a packet + came from a particular machine and that its contents were not altered + en route to you. No attempt is made to conceal or protect the contents, + only to assure their integrity. Packet authentication can be provided + separately using an <a href="glossary.html#AH">Authentication + Header</a>, described just below, or it can be included as part of the + <a href="glossary.html#ESP">ESP</a> (Encapsulated Security Payload) + service, described in the following section. That service offers + encryption as well as authentication. In either case, the <a + href="glossary.html#HMAC">HMAC</a> construct is used as the + authentication mechanism. + <p>There is a separate authentication operation at the IKE level, in + which each gateway authenticates the other. This can be done in a + variety of ways.</p> + </dd> + <dt>Encryption</dt> + <dd>Encryption allows you to conceal the contents of a message from + eavesdroppers. + <p>In IPsec this is done using a <a href="glossary.html#block">block + cipher</a> (normally <a href="glossary.html#3DES">Triple DES</a> for + Linux). In the most used setup, keys are automatically negotiated, and + periodically re-negotiated, using the <a + href="glossary.html#IKE">IKE</a> (Internet Key Exchange) protocol. In + Linux FreeS/WAN this is handled by the Pluto Daemon.</p> + <p>The IPsec protocol offering encryption is <a + href="glossary.html#ESP">ESP</a>, Encapsulated Security Payload. It can + also include a packet authentication service.</p> + </dd> +</dl> + +<p>Note that <strong>encryption should always be used with some packet +authentication service</strong>. Unauthenticated encryption is vulnerable to +<a href="glossary.html#middle">man-in-the-middle attacks</a>. Also note that +encryption does not prevent <a href="glossary.html#traffic">traffic +analysis</a>.</p> + +<h3><a name="AH.ipsec">The Authentication Header (AH)</a></h3> + +<p>Packet authentication can be provided separately from encryption by adding +an authentication header (AH) after the IP header but before the other +headers on the packet. This is the subject of this section. Details are in +RFC 2402.</p> + +<p>Each of the several headers on a packet header contains a "next protocol" +field telling the system what header to look for next. IP headers generally +have either TCP or UDP in this field. When IPsec authentication is used, the +packet IP header has AH in this field, saying that an Authentication Header +comes next. The AH header then has the next header type -- usually TCP, UDP +or encapsulated IP.</p> + +<p>IPsec packet authentication can be added in transport mode, as a +modification of standard IP transport. This is shown in this diagram from the +RFC:</p> +<pre> BEFORE APPLYING AH + ---------------------------- + IPv4 |orig IP hdr | | | + |(any options)| TCP | Data | + ---------------------------- + + AFTER APPLYING AH + --------------------------------- + IPv4 |orig IP hdr | | | | + |(any options)| AH | TCP | Data | + --------------------------------- + || + except for mutable fields</pre> + +<p>Athentication can also be used in tunnel mode, encapsulating the +underlying IP packet beneath AH and an additional IP header.</p> +<pre> || +IPv4 | new IP hdr* | | orig IP hdr* | | | + |(any options)| AH | (any options) |TCP | Data | + ------------------------------------------------ + || + | in the new IP hdr |</pre> + +<p>This would normally be used in a gateway-to-gateway tunnel. The receiving +gateway then strips the outer IP header and the AH header and forwards the +inner IP packet.</p> + +<p>The mutable fields referred to are things like the time-to-live field in +the IP header. These cannot be included in authentication calculations +because they change as the packet travels.</p> + +<h4><a name="keyed">Keyed MD5 and Keyed SHA</a></h4> + +<p>The actual authentication data in the header is typically 96 bits and +depends both on a secret shared between sender and receiver and on every byte +of the data being authenticated. The technique used is <a +href="glossary.html#HMAC">HMAC</a>, defined in RFC 2104.</p> + +<p>The algorithms involved are the <a href="glossary.html#MD5">MD5</a> +Message Digest Algorithm or <a href="glossary.html#SHA">SHA</a>, the Secure +Hash Algorithm. For details on their use in this application, see RFCs 2403 +and 2404 respectively.</p> + +<p>For descriptions of the algorithms themselves, see RFC 1321 for MD5 and <a +href="glossary.html#FIPS">FIPS</a> (Federal Information Processing Standard) +number 186 from <a href="glossary.html#NIST">NIST</a>, the US National +Institute of Standards and Technology for SHA. <a +href="biblio.html#schneier"><cite>Applied Cryptography</cite></a> covers both +in some detail, MD5 starting on page 436 and SHA on 442.</p> + +<p>These algorithms are intended to make it nearly impossible for anyone to +alter the authenticated data in transit. The sender calculates a digest or +hash value from that data and includes the result in the authentication +header. The recipient does the same calculation and compares results. For +unchanged data, the results will be identical. The hash algorithms are +designed to make it extremely difficult to change the data in any way and +still get the correct hash.</p> + +<p>Since the shared secret key is also used in both calculations, an +interceptor cannot simply alter the authenticated data and change the hash +value to match. Without the key, he or she (or even the dreaded They) cannot +produce a usable hash.</p> + +<h4><a name="sequence">Sequence numbers</a></h4> + +<p>The authentication header includes a sequence number field which the +sender is required to increment for each packet. The receiver can ignore it +or use it to check that packets are indeed arriving in the expected +sequence.</p> + +<p>This provides partial protection against <a +href="glossary.html#replay">replay attacks</a> in which an attacker resends +intercepted packets in an effort to confuse or subvert the receiver. Complete +protection is not possible since it is necessary to handle legitmate packets +which are lost, duplicated, or delivered out of order, but use of sequence +numbers makes the attack much more difficult.</p> + +<p>The RFCs require that sequence numbers never cycle, that a new key always +be negotiated before the sequence number reaches 2^32-1. This protects both +against replays attacks using packets from a previous cyclce and against <a +href="glossary.html#birthday">birthday attacks</a> on the the packet +authentication algorithm.</p> + +<p>In Linux FreeS/WAN, the sequence number is ignored for manually keyed +connections and checked for automatically keyed ones. In manual mode, there +is no way to negotiate a new key, or to recover from a sequence number +problem, so we don't use sequence numbers.</p> + +<h3><a name="ESP.ipsec">Encapsulated Security Payload (ESP)</a></h3> + +<p>The ESP protocol is defined in RFC 2406. It provides one or both of +encryption and packet authentication. It may be used with or without AH +packet authentication.</p> + +<p>Note that <strong>some form of packet authentication should +<em>always</em> be used whenever data is encrypted</strong>. Without +authentication, the encryption is vulnerable to active attacks which may +allow an enemy to break the encryption. ESP should <strong>always</strong> +either include its own authentication or be used with AH authentication.</p> + +<p>The RFCs require support for only two mandatory encryption algorithms -- +<a href="glossary.html#DES">DES</a>, and null encryption -- and for two +authentication methods -- keyed MD5 and keyed SHA. Implementers may choose to +support additional algorithms in either category.</p> + +<p>The authentication algorithms are the same ones used in the IPsec <a +href="#AH">authentication header</a>.</p> + +<p>We do not implement single DES since <a +href="politics.html#desnotsecure">DES is insecure</a>. Instead we provide <a +href="glossary.html#3DES">triple DES or 3DES</a>. This is currently the only +encryption algorithm supported.</p> + +<p>We do not implement null encryption since it is obviously insecure.</p> + +<h2><a name="modes">IPsec modes</a></h2> + +<p>IPsec can connect in two modes. Transport mode is a host-to-host +connection involving only two machines. In tunnel mode, the IPsec machines +act as gateways and trafiic for any number of client machines may be +carried.</p> + +<h3><a name="tunnel.ipsec">Tunnel mode</a></h3> + +<p>Security gateways are required to support tunnel mode connections. In this +mode the gateways provide tunnels for use by client machines behind the +gateways. The client machines need not do any IPsec processing; all they have +to do is route things to gateways.</p> + +<h3><a name="transport.ipsec">Transport mode</a></h3> + +<p>Host machines (as opposed to security gateways) with IPsec implementations +must also support transport mode. In this mode, the host does its own IPsec +processing and routes some packets via IPsec.</p> + +<h2><a name="parts">FreeS/WAN parts</a></h2> + +<h3><a name="KLIPS.ipsec">KLIPS: Kernel IPsec Support</a></h3> + +<p>KLIPS is <strong>K</strong>erne<strong>L</strong> <strong>IP</strong>SEC +<strong>S</strong>upport, the modifications necessary to support IPsec within +the Linux kernel. KILPS does all the actual IPsec packet-handling, +including</p> +<ul> + <li>encryption</li> + <li>packet authentication calculations</li> + <li>creation of ESP and AH headers for outgoing packets</li> + <li>interpretation of those headers on incoming packets</li> +</ul> + +<p>KLIPS also checks all non-IPsec packets to ensure they are not bypassing +IPsec security policies.</p> + +<h3><a name="Pluto.ipsec">The Pluto daemon</a></h3> + +<p><a href="manpage.d/ipsec_pluto.8.html">Pluto(8)</a> is a daemon which +implements the IKE protocol. It</p> +<ul> + <li>handles all the Phase one ISAKMP SAs</li> + <li>performs host authentication and negotiates with other gateways</li> + <li>creates IPsec SAs and passes the data required to run them to KLIPS</li> + <li>adjust routing and firewall setup to meet IPsec requirements. See our + <a href="firewall.html">IPsec and firewalling</a> document for + details.</li> +</ul> + +<p>Pluto is controlled mainly by the <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> configuration file.</p> + +<h3><a name="command">The ipsec(8) command</a></h3> + +<p>The <a href="manpage.d/ipsec.8.html">ipsec(8)</a> command is a front end +shellscript that allows control over IPsec activity.</p> + +<h3><a name="ipsec.conf">Linux FreeS/WAN configuration file</a></h3> + +<p>The configuration file for Linux FreeS/WAN is</p> +<pre> /etc/ipsec.conf</pre> + +<p>For details see the <a +href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> manual page .</p> + +<h2><a name="key">Key management</a></h2> + +<p>There are several ways IPsec can manage keys. Not all are implemented in +Linux FreeS/WAN.</p> + +<h3><a name="current">Currently Implemented Methods</a></h3> + +<h4><a name="manual">Manual keying</a></h4> + +<p>IPsec allows keys to be manually set. In Linux FreeS/WAN, such keys are +stored with the connection definitions in /etc/ipsec.conf.</p> + +<p><a href="glossary.html#manual">Manual keying</a> is useful for debugging +since it allows you to test the <a href="glossary.html#KLIPS">KLIPS</a> +kernel IPsec code without the <a href="glossary.html#Pluto">Pluto</a> daemon +doing key negotiation.</p> + +<p>In general, however, automatic keying is preferred because it is more +secure.</p> + +<h4><a name="auto">Automatic keying</a></h4> + +<p>In automatic keying, the <a href="glossary.html#Pluto">Pluto</a> daemon +negotiates keys using the <a href="glossary.html#IKE">IKE</a> Internet Key +Exchange protocol. Connections are automatically re-keyed periodically.</p> + +<p>This is considerably more secure than manual keying. In either case an +attacker who acquires a key can read every message encrypted with that key, +but automatic keys can be changed every few hours or even every few minutes +without breaking the connection or requiring intervention by the system +administrators. Manual keys can only be changed manually; you need to shut +down the connection and have the two admins make changes. Moreover, they have +to communicate the new keys securely, perhaps with <a +href="glossary.html#PGP">PGP</a> or <a href="glossary.html#SSH">SSH</a>. This +may be possible in some cases, but as a general solution it is expensive, +bothersome and unreliable. Far better to let <a +href="glossary.html#Pluto">Pluto</a> handle these chores; no doubt the +administrators have enough to do.</p> + +<p>Also, automatic keying is inherently more secure against an attacker who +manages to subvert your gateway system. If manual keying is in use and an +adversary acquires root privilege on your gateway, he reads your keys from +/etc/ipsec.conf and then reads all messages encrypted with those keys.</p> + +<p>If automatic keying is used, an adversary with the same privileges can +read /etc/ipsec.secrets, but this does not contain any keys, only the secrets +used to authenticate key exchanges. Having an adversary able to authenticate +your key exchanges need not worry you overmuch. Just having the secrets does +not give him any keys. You are still secure against <a +href="glossary.html#passive">passive</a> attacks. This property of automatic +keying is called <a href="glossary.html#PFS">perfect forward secrecy</a>, +abbreviated PFS.</p> + +<p>Unfortunately, having the secrets does allow an <a +href="glossary.html#active">active attack</a>, specifically a <a +href="glossary.html#middle">man-in-the-middle</a> attack. Losing these +secrets to an attacker may not be quite as disastrous as losing the actual +keys, but it is <em>still a serious security breach</em>. These secrets +should be guarded as carefully as keys.</p> + +<h3><a name="notyet">Methods not yet implemented</a></h3> + +<h4><a name="noauth">Unauthenticated key exchange</a></h4> + +<p>It would be possible to exchange keys without authenticating the players. +This would support <a href="glossary.html#carpediem">opportunistic +encryption</a> -- allowing any two systems to encrypt their communications +without requiring a shared PKI or a previously negotiated secret -- and would +be secure against <a href="glossary.html#passive">passive attacks</a>. It +would, however, be highly vulnerable to active <a +href="glossary.html#middle">man-in-the-middle</a> attacks. RFC 2408 therefore +specifies that all <a href="glossary.html#ISAKMP">ISAKMP</a> key management +interactions <em>must</em> be authenticated.</p> + +<p>There is room for debate here. Should we provide immediate security +against <a href="glossary.html#passive">passive attacks</a> and encourage +widespread use of encryption, at the expense of risking the more difficult <a +href="glossary.html#active">active attacks</a>? Or should we wait until we +can implement a solution that can both be widespread and offer security +against active attacks?</p> + +<p>So far, we have chosen the second course, complying with the RFCs and +waiting for secure DNS (see <a href="glossary.html#DNS">below</a>) so that we +can do <a href="glossary.html#carpediem">opportunistic encryption</a> +right.</p> + +<h4><a name="DNS">Key exchange using DNS</a></h4> + +<p>The IPsec RFCs allow key exchange based on authentication services +provided by <a href="glossary.html#SDNS">Secure DNS</a>. Once Secure DNS +service becomes widely available, we expect to make this the <em>primary key +management method for Linux FreeS/WAN</em>. It is the best way we know of to +support <a href="glossary.html#carpediem">opportunistic encryption</a>, +allowing two systems without a common PKI or previous negotiation to secure +their communication.</p> + +<p>We currently have code to acquire RSA keys from DNS but do not yet have +code to validate Secure DNS signatures.</p> + +<h4><a name="PKI">Key exchange using a PKI</a></h4> + +<p>The IPsec RFCs allow key exchange based on authentication services +provided by a <a href="glossary.html#PKI">PKI</a> or Public Key +Infrastructure. With many vendors selling such products and many large +organisations building these infrastructures, this will clearly be an +important application of IPsec and one Linux FreeS/WAN will eventually +support.</p> + +<p>On the other hand, this is not as high a priority for Linux FreeS/WAN as +solutions based on <a href="glossary.html#SDNS">secure DNS</a>. We do not +expect any PKI to become as universal as DNS.</p> + +<p>Some <a href="web.html#patch">patches</a> to handle authentication with +X.509 certificates, which most PKIs use, are available.</p> + +<h4><a name="photuris">Photuris</a></h4> + +<p><a href="glossary.html#photuris">Photuris</a> is another key management +protocol, an alternative to IKE and ISAKMP, described in RFCs 2522 and 2523 +which are labelled "experimental". Adding Photuris support to Linux FreeS/WAN +might be a good project for a volunteer. The likely starting point would be +the OpenBSD photurisd code.</p> + +<h4><a name="skip">SKIP</a></h4> + +<p><a href="glossary.html#SKIP">SKIP</a> is yet another key management +protocol, developed by Sun. At one point it was fairly widely used, but it +now seems moribund, displaced by IKE. Sun now (as of Solaris 8.0) ship an +IPsec implementation using IKE. We have no plans to implement SKIP. If a user +were to implement it, we would almost certainly not want to add the code to +our distribution.</p> +</body> +</html> diff --git a/doc/src/kernel.html b/doc/src/kernel.html new file mode 100644 index 000000000..a4beab417 --- /dev/null +++ b/doc/src/kernel.html @@ -0,0 +1,392 @@ +<html> +<head> +<title>Kernel configuration for FreeS/WAN</title> +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, kernel"> + +<!-- + +Written by Sandy Harris for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +CVS information: +RCS ID: $Id: kernel.html,v 1.1 2004/03/15 20:35:24 as Exp $ +Last changed: $Date: 2004/03/15 20:35:24 $ +Revision number: $Revision: 1.1 $ + +CVS revision numbers do not correspond to FreeS/WAN release numbers. +--> +</head> + +<body> + +<h1><a name="kernelconfig">Kernel configuration for FreeS/WAN</a></h1> + +<p> +This section lists many of the options available when configuring a Linux + kernel, and explains how they should be set on a FreeS/WAN IPsec + gateway.</p> + + <h2><a name="notall">Not everyone needs to worry about kernel configuration</a></h2> + + <p>Note that in many cases you do not need to mess with these.</p> + +<p> +You may have a Linux distribution which comes with FreeS/WAN installed +(see this <a href="intro.html#products">list</a>). + In that case, you need not do a FreeS/WAN installation or a kernel + configuration. Of course, you might still want to configure and rebuild your + kernel to improve performance or security. This can be done with standard + tools described in the <a href="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">Kernel HowTo</a>.</p> + + <p>If you need to install FreeS/WAN, then you do need to configure a kernel. + However, you may choose to do that using the simplest procedure:</p> + <ul> + <li>Configure, build and test a kernel for your system before adding FreeS/WAN. See the <a + href="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">Kernel HowTo</a> for details. <strong>This step cannot be + skipped</strong>. FreeS/WAN needs the results of your configuration.</li> + <li>Then use FreeS/WAN's <var>make oldgo</var> command. This sets + everything FreeS/WAN needs and retains your values everywhere else.</li> + </ul> + +<p> +This document is for those who choose to configure their FreeS/WAN kernel +themselves.</p> + +<h2><a name="assume">Assumptions and notation</a></h2> + +<p> +Help text for most kernel options is included with the kernel files, and +is accessible from within the configuration utilities. We assume +you will refer to that, and to the <a href="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">Kernel HowTo</a>, as +necessary. This document covers only the FreeS/WAN-specific aspects of the +problem.</p> + +<p> +To avoid duplication, this document section does not cover settings for +the additional IPsec-related kernel options which become available after you +have patched your kernel with FreeS/WAN patches. There is help text for +those available from within the configuration utility.</p> + + <p> +We assume a common configuration in which the FreeS/WAN IPsec gateway is +also doing ipchains(8) firewalling for a local network, and possibly +masquerading as well.</p> + +<p> +Some suggestions below are labelled as appropriate for "a true paranoid". +By this we mean they may cause inconvenience and it is not entirely clear + they are necessary, but they appear to be the safest choice. Not using them + might entail some risk. Of course one suggested mantra for security + administrators is: "I know I'm paranoid. I wonder if I'm paranoid + enough."</p> + + <h3><a name="labels">Labels used</a></h3> + +<p> +Six labels are used to indicate how options should be set. We mark the +labels with [square brackets]. For two of these labels, you have no +choice:</p> + <dl> + <dt>[required]</dt> + <dd>essential for FreeS/WAN operation.</dd> + <dt>[incompatible]</dt> + <dd>incompatible with FreeS/WAN.</dd> + </dl> + + <p>those must be set correctly or FreeS/WAN will not work</p> + + <p>FreeS/WAN should work with any settings of the others, though of course + not all combinations have been tested. We do label these in various ways, + but <em>these labels are only suggestions</em>.</p> + <dl> + <dt>[recommended]</dt> + <dd>useful on most FreeS/WAN gateways</dd> + <dt>[disable]</dt> + <dd>an unwelcome complication on a FreeS/WAN gateway.</dd> + <dt>[optional]</dt> + <dd>Your choice. We outline issues you might consider.</dd> + <dt>[anything]</dt> + <dd>This option has no direct effect on FreeS/WAN and related tools, so + you should be able to set it as you please.</dd> + </dl> + +<p> +Of course complexity is an enemy in any effort to build secure systems. +<strong>For maximum security, any feature that can reasonably be turned off +should be</strong>. "If in doubt, leave it out."</p> + + <h2><a name="kernelopt">Kernel options for FreeS/WAN</a></h2> + +<p> +Indentation is based on the nesting shown by 'make menuconfig' with a +2.2.16 kernel for the i386 architecture.</p> +<dl> + <dt><a name="maturity">Code maturity and level options</a></dt> + <dd> + <dl> + <dt><a name="devel">Prompt for development ... + code/drivers</a></dt> + <dd>[optional] If this is <var>no</var>, experimental drivers are + not shown in later menus. + <p>For most FreeS/WAN work, <var>no</var> is the preferred + setting. Using new or untested components is too risky for a + security gateway.</p> + <p>However, for some hardware (such as the author's network + cards) the only drivers available are marked + <var>new/experimental</var>. In such cases, you must enable this + option or your cards will not appear under "network device + support". A true paranoid would leave this option off and + replace the cards.</p> + </dd> + <dt>Processor type and features</dt> + <dd>[anything]</dd> + <dt>Loadable module support</dt> + <dd> + <dl> + <dt>Enable loadable module support</dt> + <dd>[optional] A true paranoid would disable this. An attacker who + has root access to your machine can fairly easily install a + bogus module that does awful things, provided modules are + enabled. A common tool for attackers is a "rootkit", a set + of tools the attacker uses once he or she has become root on your system. + The kit introduces assorted additional compromises so that the attacker + will continue to "own" your system despite most things you might + do to recovery the situation. For Linux, there is a tool called + <a href="http://www.sans.org/newlook/resources/IDFAQ/knark.htm">knark</a> + which is basically a rootkit packaged as a kernel module. + <p>With modules disabled, an attacker cannot install a bogus module. + The only way + he can achieve the same effects is to install a new kernel and + reboot. This is considerably more likely to be noticed. + <p>Many FreeS/WAN gateways run with modules enabled. This + simplifies some administrative tasks and some ipchains features + are available only as modules. Once an enemy has root on your + machine your security is nil, so arguably defenses which come + into play only in that situation are pointless.</p> + <p> + + </dd> + <dt>Set version information ....</dt> + <dd>[optional] This provides a check to prevent loading modules + compiled for a different kernel.</dd> + <dt>Kernel module loader</dt> + <dd>[disable] It gives little benefit on a typical FreeS/WAN gate + and entails some risk.</dd> + </dl> + </dd> + <dt>General setup</dt> + <dd>We list here only the options that matter for FreeS/WAN. + <dl> + <dt>Networking support</dt> + <dd>[required]</dd> + <dt>Sysctl interface</dt> + <dd>[optional] If this option is turned on and the + <var>/proc</var> filesystem installed, then you can control + various system behaviours by writing to files under + <var>/proc/sys</var>. For example: + <pre> echo 1 > /proc/sys/net/ipv4/ipforward</pre> + turns IP forwarding on. + <p>Disabling this option breaks many firewall scripts. A true + paranoid would disable it anyway since it might conceivably be + of use to an attacker.</p> + </dd> + </dl> + </dd> + <dt>Plug and Play support</dt> + <dd>[anything]</dd> + <dt>Block devices</dt> + <dd>[anything]</dd> + <dt>Networking options</dt> + <dd> + <dl> + <dt>Packet socket</dt> + <dd>[optional] This kernel feature supports tools such as + tcpdump(8) which communicate directly with network hardware, + bypassing kernel protocols. This is very much a two-edged sword: + <ul> + <li>such tools can be very useful to the firewall admin, + especially during initial testing</li> + <li>should an evildoer breach your firewall, such tools could + give him or her a great deal of information about the rest + of your network</li> + </ul> + We recommend disabling this option on production gateways.</dd> + <dt><a name="netlink">Kernel/User netlink socket</a></dt> + <dd>[optional] Required if you want to use <a href="#adv">advanced + router</a> features.</dd> + <dt>Routing messages</dt> + <dd>[optional]</dd> + <dt>Netlink device emulation</dt> + <dd>[optional]</dd> + <dt>Network firewalls</dt> + <dd>[recommended] You need this if the IPsec gateway also + functions as a firewall. + <p>Even if the IPsec gateway is not your primary firewall, we + suggest setting this so that you can protect the gateway with at + least basic local packet filters.</p> + </dd> + <dt>Socket filtering</dt> + <dd>[disable] This enables an older filtering interface. We suggest + using ipchains(8) instead. To do that, set the "Network + firewalls" option just above, and not this one.</dd> + <dt>Unix domain sockets</dt> + <dd>[required] These sockets are used for communication between the + <a href="manpage.d/ipsec.8.html">ipsec(8)</a> + commands and the <a href="manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</a> + daemon.</dd> + <dt>TCP/IP networking</dt> + <dd>[required] + <dl> + <dt>IP: multicasting</dt> + <dd>[anything]</dd> + <dt><a name="adv">IP: advanced router</a></dt> + <dd>[optional] This gives you policy routing, which some + people have used to good advantage in their scripts for + FreeS/WAN gateway management. It is not used in our + distributed scripts, so not required unless you want it + for custom scripts. It requires the <a + href="#netlink">netlink</a> interface between kernel code + and the iproute2(8) command.</dd> + <dt>IP: kernel level autoconfiguration</dt> + <dd>[disable] It gives little benefit on a typical FreeS/WAN + gate and entails some risk.</dd> + <dt>IP: firewall packet netlink device</dt> + <dd>[disable]</dd> + <dt>IP: transparent proxy support</dt> + <dd>[optional] This is required in some firewall configurations, + but should be disabled unless you have a definite need for it. + </dd> + <dt>IP: masquerading</dt> + <dd>[optional] Required if you want to use + <a href="glossary.html#non-routable">non-routable</a> private + IP addresses for your local network.</dd> + <dt>IP: Optimize as router not host</dt> + <dd>[recommended]</dd> + <dt>IP: tunneling</dt> + <dd>[required]</dd> + <dt>IP: GRE tunnels over IP</dt> + <dd>[anything]</dd> + <dt>IP: aliasing support</dt> + <dd>[anything]</dd> + <dt>IP: ARP daemon support (EXPERIMENTAL)</dt> + <dd>Not required on most systems, but might prove useful on + heavily-loaded gateways.</dd> + <dt>IP: TCP syncookie support</dt> + <dd>[recommended] It provides a defense against a <a + href="glossary.html#DOS">denial of + service attack</a> which uses bogus TCP connection + requests to waste resources on the victim machine.</dd> + <dt>IP: Reverse ARP</dt> + <dd></dd> + <dt>IP: large window support</dt> + <dd>[recommended] unless you have less than 16 meg RAM</dd> + </dl> + </dd> + <dt>IPv6</dt> + <dd>[optional] FreeS/WAN does not currently support IPv6, though work on + integrating FreeS/WAN with the Linux IPv6 stack has begun. + <a href="compat.html#ipv6">Details</a>. + <p> + It should be possible to use IPv4 FreeS/WAN on a machine which also + does IPv6. This combination is not yet well tested. We would be quite + interested in hearing results from anyone expermenting with it, via the + <a href="mail.html">mailing list</a>. + <p> + We do not recommend using IPv6 on production FreeS/WAN gateways until + more testing has been done. + </dd> + <dt>Novell IPX</dt> + <dd>[disable]</dd> + <dt>Appletalk</dt> + <dd>[disable] Quite a few Linux installations use IP but also have + some other protocol, such as Appletalk or IPX, for communication + with local desktop machines. In theory it should be possible to + configure IPsec for the IP side of things without interfering + with the second protocol. + <p>We do not recommend this. Keep the software on your gateway + as simple as possible. If you need a Linux-based Appletalk or + IPX server, use a separate machine.</p> + </dd> + </dl> + </dd> + <dt>Telephony support</dt> + <dd>[anything]</dd> + <dt>SCSI support</dt> + <dd>[anything]</dd> + <dt>I2O device support</dt> + <dd>[anything]</dd> + <dt>Network device support</dt> + <dd>[anything] should work, but there are some points to note. + <p>The development team test almost entirely on 10 or 100 megabit + Ethernet and modems. In principle, any device that can do IP should be + just fine for IPsec, but in the real world any device that has not + been well-tested is somewhat risky. By all means try it, but don't bet + your project on it until you have solid test results.</p> + <p>If you disabled experimental drivers in the <a + href="#maturity">Code maturity</a> section above, then those drivers + will not be shown here. Check that option before going off to hunt for + missing drivers.</p> + <p>If you want Linux to automatically find more than one ethernet + interface at boot time, you need to:</p> + <ul> + <li>compile the appropriate driver(s) into your kernel. Modules will + not work for this</li> + <li>add a line such as +<pre> + append="ether=0,0,eth0 ether=0,0,eth1" +</pre> + to your /etc/lilo.conf file. In some cases you may need to specify + parameters such as IRQ or base address. The example uses "0,0" + for these, which tells the system to search. If the search does not + succeed on your hardware, then you should retry with explicit parameters. + See the lilo.conf(5) man page for details.</li> + <li>run lilo(8)</li> + </ul> + Having Linux find the cards this way is not necessary, but is usually more + convenient than loading modules in your boot scripts.</dd> + <dt>Amateur radio support</dt> + <dd>[anything]</dd> + <dt>IrDA (infrared) support</dt> + <dd>[anything]</dd> + <dt>ISDN subsystem</dt> + <dd>[anything]</dd> + <dt>Old CDROM drivers</dt> + <dd>[anything]</dd> + <dt>Character devices</dt> + <dd>The only required character device is: + <dl> + <dt>random(4)</dt> + <dd>[required] This is a source of <a href="glossary.html#random">random</a> + numbers which are required for many cryptographic protocols, + including several used in IPsec. + <p>If you are comfortable with C source code, it is likely a + good idea to go in and adjust the <var>#define</var> lines in + <var>/usr/src/linux/drivers/char/random.c</var> to ensure that + all sources of randomness are enabled. Relying solely on + keyboard and mouse randomness is dubious procedure for a gateway + machine. You could also increase the randomness pool size from + the default 512 bytes (128 32-bit words).</p> + </dd> + </dl> + <dt>Filesystems</dt> + <dd>[anything] should work, but we suggest limiting a gateway + machine to the standard Linux ext2 filesystem in most + cases.</dd> + <dt>Network filesystems</dt> + <dd>[disable] These systems are an unnecessary risk on an IPsec + gateway.</dd> + <dt>Console drivers</dt> + <dd>[anything]</dd> + <dt>Sound</dt> + <dd>[anything] should work, but we suggest enabling sound only if + you plan to use audible alarms for firewall problems.</dd> + <dt>Kernel hacking</dt> + <dd>[disable] This might be enabled on test machines, but should + not be on production gateways.</dd> + </dl> + </dl> +</body> +</html> diff --git a/doc/src/mail.html b/doc/src/mail.html new file mode 100644 index 000000000..e26f025a0 --- /dev/null +++ b/doc/src/mail.html @@ -0,0 +1,250 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN mailing lists</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, mailing, list"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: mail.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="lists">Mailing lists and newsgroups</a></h1> + +<h2><a name="list.fs">Mailing lists about FreeS/WAN</a></h2> + +<h3><a name="projlist">The project mailing lists</a></h3> + +<p>The Linux FreeS/WAN project has several email lists for user support, bug +reports and software development discussions.</p> + +<p>We had a single list on clinet.fi for several years (Thanks, folks!), then +one list on freeswan.org, but now we've split into several lists:</p> +<dl> + <dt><a + href="mailto:users-request@lists.freeswan.org?body=subscribe">users</a></dt> + <dd><ul> + <li>The general list for discussing use of the software</li> + <li>The place for seeking <strong>help with problems</strong> (but + please check the <a href="faq.html">FAQ</a> first).</li> + <li>Anyone can post.</li> + </ul> + </dd> + <dt><a + href="mailto:bugs-request@lists.freeswan.org?body=subscribe">bugs</a></dt> + <dd><ul> + <li>For <strong>bug reports</strong>.</li> + <li>If you are not certain what is going on -- could be a bug, a + configuration error, a network problem, ... -- please post to the + users list instead.</li> + <li>Anyone can post.</li> + </ul> + </dd> + <dt><a + href="mailto:design-request@lists.freeswan.org?body=subscribe">design</a></dt> + <dd><ul> + <li><strong>Design discussions</strong>, for people working on + FreeS/WAN development or others with an interest in design and + security issues.</li> + <li>It would be a good idea to read the existing design papers (see + this <a href="intro.html#applied">list</a>) before posting.</li> + <li>Anyone can post.</li> + </ul> + </dd> + <dt><a + href="mailto:announce-request@lists.freeswan.org?body=subscribe">announce</a></dt> + <dd><ul> + <li>A <strong>low-traffic</strong> list.</li> + <li><strong>Announcements</strong> about FreeS/WAN and related + software.</li> + <li>All posts here are also sent to the users list. You need not + subscribe to both.</li> + <li>Only the FreeS/WAN team can post.</li> + <li>If you have something you feel should go on this list, send it to + <var>announce-admin@lists.freeswan.org</var>. Unless it is obvious, + please include a short note explaining why we should post it.</li> + </ul> + </dd> + <dt><a + href="mailto:briefs-request@lists.freeswan.org?body=subscribe">briefs</a></dt> + <dd><ul> + <li>A <strong>low-traffic</strong> list.</li> + <li><strong>Weekly summaries</strong> of activity on the users + list.</li> + <li>All posts here are also sent to the users list. You need not + subscribe to both.</li> + <li>Only the FreeS/WAN team can post.</li> + </ul> + </dd> +</dl> + +<p>To subscribe to any of these, you can:</p> +<ul> + <li>just follow the links above</li> + <li>use our <a href="http://www.freeswan.org/mail.html">web + interface</a></li> + <li>send mail to <var>listname</var>-request@lists.freeswan.org with a + one-line message body "subscribe"</li> +</ul> + +<p>Archives of these lists are available via the <a +href="http://www.freeswan.org/mail.html">web interface</a>.</p> + +<h4><a name="which.list">Which list should I use?</a></h4> + +<p>For most questions, please check the <a href="faq.html">FAQ</a> first, and +if that does not have an answer, ask on the users list. "My configuration +doesn't work." does not belong on the bugs list, and "Can FreeS/WAN do +such-and-such" or "How do I configure it to..." do not belong in design +discussions.</p> + +<p>Cross-posting the same message to two or more of these lists is +discouraged. Quite a few people read more than one list and getting multiple +copies is annoying.</p> + +<h4><a name="policy.list">List policies</a></h4> + +<p><strong>US citizens or residents are asked not to post code to the lists, +not even one-line bug fixes</strong>. The project cannot accept code which +might entangle it in US <a href="politics.html#exlaw">export +restrictions</a>.</p> + +<p>Non-subscribers can post to some of these lists. This is necessary; +someone working on a gateway install who encounters a problem may not have +access to a subscribed account.</p> + +<p>Some spam turns up on these lists from time to time. For discussion of why +we do not attempt to filter it, see the <a href="faq.html#spam">FAQ</a>. +Please do not clutter the lists with complaints about this.</p> + +<h3><a name="archive">Archives of the lists</a></h3> + +<p>Searchable archives of the old single list have existed for some time. At +time of writing, it is not yet clear how they will change for the new +multi-list structure.</p> +<ul> + <li><a href="http://www.sandelman.ottawa.on.ca/linux-ipsec">Canada</a></li> + <li><a href="http://www.nexial.com">Holland</a></li> +</ul> + +<p>Note that these use different search engines. Try both.</p> + +<p>Archives of the new lists are available via the <a +href="http://www.freeswan.org/mail.html">web interface</a>.</p> + +<h2><a name="indexes">Indexes of mailing lists</a></h2> + +<p><a href="http://paml.net/">PAML</a> is the standard reference for +<strong>P</strong>ublicly <strong>A</strong>ccessible +<strong>M</strong>ailing <strong>L</strong>ists. When we last checked, it had +over 7500 lists on an amazing variety of topics. It also has FAQ information +and a search engine.</p> + +<p>There is an index of <a +href="http://oslab.snu.ac.kr/~djshin/linux/mail-list/index.shtml">Linux +mailing lists</a> available.</p> + +<p>A list of <a +href="http://xforce.iss.net/maillists/otherlists.php">computer security +mailing lists</a>, with descriptions.</p> + +<h2><a name="otherlists">Lists for related software and topics</a></h2> + +<p>Most links in this section point to subscription addresses for the various +lists. Send the one-line message "subscribe <var>list_name</var>" to +subscribe to any of them.</p> + +<h3>Products that include FreeS/WAN</h3> + +<p>Our introduction document gives a <a href="intro.html#products">list of +products that include FreeS/WAN</a>. If you have, or are considering, one of +those, check the supplier's web site for information on mailing lists for +their users.</p> + +<h3><a name="linux.lists">Linux mailing lists</a></h3> +<ul> + <li><a + href="mailto:majordomo@vger.kernel.org">linux-admin@vger.kernel.org</a>, + for Linux system administrators</li> + <li><a + href="mailto:netfilter-request@lists.samba.org">netfilter@lists.samba.org</a>, + about Netfilter, which replaces IPchains in kernels 2.3.15 and later</li> + <li><a + href="mailto:security-audit-request@ferret.lmh.ox.ac.uk">security-audit@ferret.lmh.ox.ac.uk</a>, + for people working on security audits of various Linux programs</li> + <li><a + href="mailto:securedistros-request@humbolt.geo.uu.nl">securedistros@humbolt.geo.uu.nl</a>, + for discussion of issues common to all the half dozen projects working on + secure Linux distributions.</li> +</ul> + +<p>Each of the scure distribution projects also has its own web site and +mailing list. Some of the sites are:</p> +<ul> + <li><a href="http://bastille-linux.org/">Bastille Linux</a> scripts to + harden Redhat, e.g. by changing permissions and modifying inialisation + scripts</li> + <li><a href="http://immunix.org/">Immunix</a> take a different approach, + using a modified compiler to build kernel and utilities with better + resistance to various types of overflow and exploit</li> + <li>the <a href="glossary.html#NSA">NSA</a> have contractors working on a + <a href="glossary.html#SElinux">Security Enhanced Linux</a>, primarily + adding stronger access control mechanisms. You can download the current + version (which interestingly is under GPL and not export resrtricted) or + subscribe to the mailing list from the <a + href="http://www.nsa.gov/selinux">project web page</a>.</li> +</ul> + +<h3><a name="ietf">Lists for IETF working groups</a></h3> + +<p>Each <a href="glossary.html#IETF">IETF</a> working group has an associated +mailing list where much of the work takes place.</p> +<ul> + <li><a + href="mailto:majordomo@lists.tislabs.com">ipsec@lists.tislabs.com</a>, + the IPsec <a + href="http://www.ietf.org/html.charters/ipsec-charter.html">working + group</a>. This is where the protocols are discussed, new drafts + announced, and so on. By now, the IPsec working group is winding down + since the work is essentially complete. A <a + href="http://www.sandelman.ottawa.on.ca/ipsec/">list archive</a> is + available.</li> + <li><a href="mailto:ipsec-policy-request@vpnc.org">IPsec policy</a> list, + and its <a href="http://www.vpnc.org/ipsec-policy/">archive</a></li> + <li><a href="mailto:ietf-ipsra-request@vpnc.org">IP secure remote + access</a> list, and its <a + href="http://www.vpnc.org/ietf-ipsra/mail-archive/">archive</a></li> +</ul> + +<h3><a name="other">Other mailing lists</a></h3> +<ul> + <li><a + href="mailto:ipc-announce-request@privacy.org">ipc-announce@privacy.org</a> + a low-traffic list with announcements of developments in privacy, + encryption and online civil rights</li> + <li>a VPN mailing list's <a + href="http://kubarb.phsx.ukans.edu/~tbird/vpn.html">home page</a></li> +</ul> + +<h2><a name="newsgroups">Usenet newsgroups</a></h2> +<ul> + <li>sci.crypt</li> + <li>sci.crypt.research</li> + <li>comp.dcom.vpn</li> + <li>talk.politics.crypto</li> +</ul> +</body> +</html> diff --git a/doc/src/makecheck.html b/doc/src/makecheck.html new file mode 100644 index 000000000..7fa3a3bcb --- /dev/null +++ b/doc/src/makecheck.html @@ -0,0 +1,684 @@ +<html> +<head> +<title>FreeS/WAN "make check" guide</title> +<!-- Changed by: Michael Richardson, 02-Apr-2003 --> +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, testing, User-Mode-Linux, UML"> + +<!-- + +Written by Michael Richardson for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +$Id: makecheck.html,v 1.1 2004/03/15 20:35:24 as Exp $ + +$Log: makecheck.html,v $ +Revision 1.1 2004/03/15 20:35:24 as +added files from freeswan-2.04-x509-1.5.3 + +Revision 1.25 2003/04/02 20:28:33 mcr + document for NETJIGVERBOSE environment variable. + +Revision 1.24 2003/04/02 02:17:52 mcr + added documentation on "PACKETRATE" + +Revision 1.23 2003/02/27 09:28:24 mcr + added documentation for *_RUN2_SCRIPT. + +Revision 1.22 2003/02/20 20:00:44 mcr + added documentation for ${host}HOST. + +Revision 1.21 2003/02/20 19:56:11 mcr + documented new umlXhost test case. + +Revision 1.20 2002/12/06 02:11:42 mcr + added new test type, module_compile. + +Revision 1.19 2002/12/04 03:47:06 mcr + added documentation of various *TESTDEBUG options in + the testing environment. + +Revision 1.18 2002/10/31 19:01:31 mcr + documentation for RUN_*_SCRIPT. + +Revision 1.17 2002/09/11 19:43:36 mcr + added documentation on format of TESTLIST. + +Revision 1.16 2002/09/11 19:26:48 mcr + renamed umlpluto -> umlplutotest. + +Revision 1.15 2002/07/29 22:27:12 mcr + added kernel_patch_test test type. + +Revision 1.14 2002/06/19 18:24:44 mcr + renamed SCRIPT to INIT_SCRIPT. + +Revision 1.13 2002/06/19 10:06:07 mcr + added nightly.html to the documentation tree. + +Revision 1.12 2002/06/19 09:19:26 mcr + wrote documentation for umlpluto parts of makecheck, + and adjusted scripts for consistency. + +Revision 1.11 2002/06/19 07:26:31 mcr + added FINAL_SCRIPT to be run after sending packets through. + renamed "SCRIPT" to "INIT_SCRIPT" (left compat variable) + +Revision 1.10 2002/06/17 05:40:57 mcr + Added test cases for the "make rpm" machinery. + +Revision 1.9 2002/06/08 17:12:49 mcr + added new libtest test type for use in testing libfreeswan + +Revision 1.8 2002/05/27 00:19:38 mcr + removed reference to single_netjig.png because mkhtml does not + grok it. + +Revision 1.7 2002/05/07 01:31:52 mcr + documented the new "mkinsttest" target type. + +Revision 1.6 2002/05/05 23:10:50 mcr + added documentation of $TEST_TYPE variable. + +Revision 1.5 2002/04/19 22:48:41 mcr + added documentation on NETJIGDEBUG and CONSOLEDIFFDEBUG. + +Revision 1.4 2002/04/01 23:59:46 mcr + added documentation on REF_{PUB,PRIV}_FILTER. + +Revision 1.3 2002/04/01 23:38:46 mcr + redo of updates to makecheck + +Revision 1.2 2002/03/12 21:12:07 mcr + initial stab at documentation on klips testing infrastructure. + + +--> +</head> + +<body> + +<h1><a name="makecheck">How to configure to use "make check"</a></h1> + +<H2>What is "make check"</H2> +<p> +"make check" is a target in the top level makefile. It takes care of +running a number of unit and system tests to confirm that FreeSWAN has +been compiled correctly, and that no new bugs have been introduced. +</p> +<p> +As FreeSWAN contains both kernel and userspace components, doing testing +of FreeSWAN requires that the kernel be simulated. This is typically difficult +to do as a kernel requires that it be run on bare hardware. A technology +has emerged that makes this simpler. This is +<A HREF="http://user-mode-linux.sourceforge.net">User Mode Linux</A>. +</p> + +<p> +User-Mode Linux is a way to build a Linux kernel such that it can run as a process +under another Linux (or in the future other) kernel. Presently, this can only be +done for 2.4 guest kernels. The host kernel can be 2.2 or 2.4. +</p> + +<p> +"make check" expects to be able to build User-Mode Linux kernels with FreeSWAN included. +To do this it needs to have some files downloaded and extracted prior +to running "make check". This is described in the +<A HREF="umltesting.html">UML testing</A> document. +</p> + +<p> +After having run the example in the UML testing document and +successfully brought up the four machine combination, you are ready to +use "make check" +</p> + +<h2>Running "make check"</h2> +<p> +"make check" works by walking the FreeSWAN source tree invoking the +"check" target at each node. At present there are tests defined only +for the <CODE>klips</CODE> directory. These tests will use the UML +infrastructure to test out pieces of the <CODE>klips</CODE> code. +</p> +<p> +The results of the tests can be recorded. If the environment variable +<CODE>$REGRESSRESULTS</CODE> is non-null, then the results of each +test will be recorded. This can be used as part of a nightly +regression testing system, see +<A HREF="nightly.html">Nightly testing</A> for more details. +</p> +<p> +"make check" otherwise prints a minimal amount of output for each +test, and indicates pass/fail status of each test as they are run. +Failed tests do not cause failure of the target in the form of exit +codes. +</p> + +<H1>How to write a "make check" test</H1> + +<h2>Structure of a test</h2> + +<p> +Each test consists of a set of directories under <CODE>testing/</CODE>. +There are directories for <CODE>klips</CODE>, <CODE>pluto</CODE>, <CODE>packaging</CODE> +and <CODE>libraries</CODE>. +Each directory has a list of tests to run is stored in a file called <CODE>TESTLIST</CODE> in that directory. e.g. <CODE>testing/klips/TESTLIST</CODE>. +</P> + +<H2 NAME="TESTLIST">The TESTLIST</H2> +<P> +This isn't actually a shell script. It just looks like one. Some tools other than +/bin/sh process it. Lines that start with # are comments. </P> + +<PRE> +# test-kind directory-containing-test expectation [PR#] +</PRE> + +<P>The first word provides the test type, detailed below. </P> +<P> The second word is the name of the test to run. This the directory +in which the test case is to be found..</P> +<P>The third word may be one of: +<DL> +<DT> blank/good</DT> +<DD>the test is believed to function, report failure</DD> +<DT> bad</DT> +<DD> the test is known to fail, report unexpected success</DD> +<DT> suspended</DT> +<DD> the test should not be run</DD> +</DL> + +<P> +The fourth word may be a number, which is a PR# if the test is +failing. +</P> + +<H2>Test kinds</H2> +The test types are: + +<DL> +<DT>skiptest</DT> +<DD>means run no test.</DD> +<DT>ctltest</DT> +<DD>means run a single system without input/output.</DD> +<DT>klipstest</DT> +<DD>means run a single system with input/output networks</DD> +<DT><A HREF="#umlplutotest">umlplutotest</A></DT> +<DD>means run a pair of systems</DD> +<DT><A HREF="#umlXhost">umlXhost</A></DT> +<DD>run an arbitrary number of systems</DT> +<DT>suntest (TBD)</DT> +<DD>means run a quad of east/west/sunrise/sunset</DD> +<DT>roadtest (TBD)</DT> +<DD>means run a trio of east-sunrise + warrior</DD> +<DT>extrudedtest (TBD)</DT> +<DD>means run a quad of east-sunrise + warriorsouth + park</DD> +<DT>mkinsttest</TD> +<DD>a test of the "make install" machinery.</DD> +<DT>kernel_test_patch</TD> +<DD>a test of the "make kernelpatch" machinery.</DD> +</DL> + +Tests marked (TBD) have yet to be fully defined. +</p> + +<p> +Each test directory has a file in it called <CODE>testparams.sh</CODE>. +This file sets a number of environment variables to define the +parameters of the test. +</p> + +<H2>Common parameters</H2> +<DL> +<DT>TESTNAME</DT> +<DD>the name of the test (repeated for checking purposes)</DD> + +<DT>TEST_TYPE</DT> +<DD>the type of the test (repeat of type type above)</DD> + +<DT>TESTHOST</DT> +<DD>the name of the UML machine to run for the test, typically "east" + or "west"</DD> + +<DT>TEST_PURPOSE</DT> +<DD>The purpose of the test is one of: + +<DL> +<DT>goal</DT> +<DD>The goal purpose is where a test is defined for code that is not yet +finished. The test indicates when the goals have in fact been reached.</DD> +<DT>regress</DT> +<DD>This is a test to determine that a previously existing bug has been repaired. This +test will initially be created to reproduce the bug in isolation, and then the bug will +be fixed.</DD> +<DT>exploit</DT> +<DD>This is a set of packets/programs that causes a vulnerability to be +exposed. It is a specific variation of the regress option.</DD> +</DL> +</DD> + +<DT>TEST_GOAL_ITEM<DT> +<DD>in the case of a goal test, this is a reference to the requirements document</DD> + +<DT>TEST_PROB_REPORT</DT> +<DD>in the case of regression test, this the problem report number from GNATS</DD> + +<DT>TEST_EXPLOIT_URL</DT> +<DD>in the case of an exploit, this is a URL referencing the paper explaining +the origin of the test and the origin of exploit software</DD> + +<DT>REF_CONSOLE_OUTPUT</DT> +<DD>a file in the test directory that contains the sanitized console + output against which to compare the output of the actual test.</DD> +<DT>REF_CONSOLE_FIXUPS</DT> +<DD>a list of scripts (found in <CODE>klips/test/fixups</CODE>) to + apply to sanitize the console output of the machine under test. + These are typically perl, awk or sed scripts that remove things in + the kernel output that change each time the test is run and/or + compiled. +</DD> +<DT>INIT_SCRIPT</DT> +<DD><p>a file of commands that is fed into the virtual machine's console + in single user mode prior to starting the tests. This file will + usually set up any eroute's and SADB entries that are required for + the test. </p> +<p>Lines beginning with # are skipped. Blank lines are + skipped. Otherwise, a shell prompted is waited for each time + (consisting of <CODE>\n#</CODE>) and then the command is sent. + Note that the prompt is waited for before the command and not after, + so completion of the last command in the script is not + required. This is often used to invoke a program to monitor the + system, e.g. <CODE>ipsec pf_key</CODE>. +</P> +<DT>RUN_SCRIPT</DT> +<DD><P>a file of commands that is fed into the virtual machine's console + in single user mode, before the packets are sent. On single machine + tests, this script doesn't provide any more power than INIT_SCRIPT, + but is implemented for consistency's sake.</P> +<DT>FINAL_SCRIPT</DT> +<DD><p>a file of commands that is fed into the virtual machine's console + in single user mode after the final packet is sent. Similar to INIT_SCRIPT, + above. If not specified, then the single command "halt" is sent. + If specified, then the script should end with a halt command to + nicely shutdown the UML. +</P> +<DT>CONSOLEDIFFDEBUG</DT> +<DD>If set to "true" then the series of console fixups (see REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should be set to "false", or unset otherwise)</DD> +<DT>NETJIGDEBUG</DT> +<DD>If set to "true" then the series of console fixups (see REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should be set to "false", or unset otherwise)</DD> +<DT>NETJIGTESTDEBUG</DT> +<DD> If set to "netjig", then the results of talking to the <CODE>uml_netjig</CODE> +will be printed to stderr during the test. In addition, the jig will +be invoked with --debug, which causes it to log its process ID, and +wait 60 seconds before continuing. This can be used if you are trying +to debug the <CODE>uml_netjig</CODE> program itself.</DT> +<DT>HOSTTESTDEBUG</DT> +<DD> If set to "hosttest", then the results of taling to the consoles of the UMLs will +be printed to stderr during the test.</DT> +<DT>NETJIGWAITUSER</DT> +<DD> If set to "waituser", then the scripts will wait forever for user + input before they shut the tests down. Use this is if you are + debugging through the kernel.</DD> + +<DT>PACKETRATE</DT> +<DD> A number, in miliseconds (default is 500ms) at which packets will + be replayed by the netjig.</DD> +</DL> + + +<H2>KLIPStest paramaters</H2> +<P> +The klipstest function starts a program +(<CODE>testing/utils/uml_netjig/uml_netjig</CODE>) to +setup a bunch of I/O sockets (that simulate network interfaces). It +then exports the references to these sockets to the environment and +invokes (using system()) a given script. It waits for the script to +finish. +</P> + +<!-- <IMG SRC="single_netjig.png" ALT="block diagram of uml_netjig"> --> + +<P> +The script invoked (<CODE>testing/utils/host-test.tcl</CODE>) is a TCL +<A HREF="http://expect.nist.gov/">expect</A> script that arranges to start the UML +and configure it appropriately for the test. The configuration is done +with the script given above for <VAR>INIT_SCRIPT</VAR>. The TCL script then forks, +leaves the UML in the background and exits. uml_netjig continues. It then +starts listening to the simulated network answering ARPs and inserting +packets as appropriate. +</P> + +<P> +The klipstest function invokes <CODE>uml_netjig</CODE> with arguments +to capture output from network interface(s) and insert packets as +appropriate: +<DL> +<DT>PUB_INPUT</DT> +<DD>a <A HREF="http://www.tcpdump.org/">pcap</A> file to feed in on + the public (encrypted) interface. (typically, eth1)</DD> +<DT>PRIV_INPUT</DT> +<DD>a pcap file to feed in on the private (plain-text) interface + (typically, eth0).</DD> +<DT>REF_PUB_OUTPUT</DT> +<DD>a text file containing tcpdump output. Packets on the public + (eth1) interface are captured to a + <A HREF="http://www.tcpdump.org/">pcap</A> file by + <CODE>uml_netjig</CODE>. The klipstest function then uses tcpdump on + the file to produce text output, which is compared to the file given.</DD> +<DT>REF_PUB_FILTER</DT> +<DD>a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".</DD> +<DT>REF_PRIV_OUTPUT</DT> +<DD>a text file containing tcpdump output. Packets on the private + (eth0) interface are captured and compared after conversion by + tcpdump, as with <VAR>REFPUBOUTPUT</VAR>.</DD> +<DT>REF_PRIV_FILTER</DT> +<DD>a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".</DD> +<DT>EXITONEMPTY</DT> +<DD>a flag for <CODE>uml_netjig</CODE>. It should contain + "--exitonempty" of uml_netjig should exit when all of the input + (<VAR>PUBINPUT</VAR>,<VAR>PRIVINPUT</VAR>) packets have been injected.</DD> +<DT>ARPREPLY</DT> +<DD>a flag for <CODE>uml_netjig</CODE>. It should contain "--arpreply" + if <CODE>uml_netjig</CODE> should reply to ARP requests. One will + typically set this to avoid having to fudge the ARP cache manually.</DD> +<DT>TCPDUMPFLAGS</DT> +<DD>a set of flags for the tcpdump used when converting captured + output. Typical values will include "-n" to turn off DNS, and often + "-E" to set the decryption key (tcpdump 3.7.1 and higher only) for + ESP packets. The "-t" flag (turn off timestamps) is provided automatically</DD> + +<DT>NETJIG_EXTRA</DT> +<DD>additional comments to be sent to the netjig. This may arrange to + record or create additional networks, or may toggle options. +</DL> + +<H2>mkinsttest paramaters</H2> +<P> +The basic concept of the <CODE>mkinsttest</CODE> test type is that it +performs a "make install" to a temporary $DESTDIR. The resulting tree can then +be examined to determine if it was done properly. The files can be uninstalled +to determine if the file list was correct, or the contents of files can be +examined more precisely. +</P> + +<DL> +<DT>INSTALL_FLAGS</DT> +<DD>If set, then an install will be done. This provides the set of flags to +provide for the install. The target to be used (usually "install") must be +among the flags. </DD> +<DT>POSTINSTALL_SCRIPT</DT> +<DD>If set, a script to run after initial "make install". Two arguments are provided: an absolute path to the root of the FreeSWAN src tree, and an absolute path to the temporary installation area.</DD> +<DT>INSTALL2_FLAGS</DT> +<DD>If set, a second install will be done using these flags. Similarly to +INSTALL_FLAGS, the target must be among the flags. </DD> +<DT>UNINSTALL_FLAGS</DT> +<DD>If set, an uninstall will be done using these flags. Similarly to +INSTALL_FLAGS, the target (usually "uninstall") must be among the flags.</DD> +<DT>REF_FIND_f_l_OUTPUT</DT> +<DD>If set, a <CODE>find $ROOT ( -type f -or -type -l )</CODE> will be done to get a list of a real files and symlinks. The resulting file will be compared +to the file listed by this option.</DD> +<DT>REF_FILE_CONTENTS</DT> +<DD>If set, it should point to a file containing records for the form: +<PRE> + <VARIABLE>reffile</VARIABLE> <VARIABLE>samplefile</VARIABLE> +</PRE> +one record per line. A diff between the provided reference file, and the +sample file (located in the temporary installation root) will be done for +each record. +</DD> +</DL> + +<H2>rpm_build_install_test paramaters</H2> +<P> +The <CODE>rpm_build_install_test</CODE> type is to verify that the proper +packing list is produced by "make rpm", and that the mechanisms for +building the kernel modules produce consistent results. +</P> + +<DL> +<DT>RPM_KERNEL_SOURCE</DT> +<DD>Point to an extracted copy of the RedHat kernel source code. Variables +from the environment may be used.</DD> +<DT>REF_RPM_CONTENTS</DT> +<DD>This is a file containing one record per line. Each record consists +of a RPM name (may contain wildcards) and a filename to compare the +contents to. The RPM will be located and a file list will be produced with +rpm2cpio.</DD> +</DL> + +<H2>libtest paramaters</H2> +<P> +The libtest test is for testing library routines. The library file is +expected to provided an <CODE>#ifdef</CODE> by the name of +<VAR>library</VAR><CODE_MAIN</CODE>. +The libtest type invokes the C compiler to compile this file, links it against +<CODE>libfreeswan.a</CODE> (to resolve any other dependancies) and runs the +test with the <CODE>-r</CODE> argument to invoke a regression test.</P> +<P>The library test case is expected to do a self-test, exiting with status code 0 if everything is okay, and with non-zero otherwise. A core dump (exit code greater than 128) is noted specifically. +</P> +<P> +Unlike other tests, there are no subdirectories required, or other +parameters to set. +</P> + +<H2 NAME="umlplutotest">umlplutotest paramaters</H2> +<P> +The umlplutotest function starts a pair of user mode line processes. +This is a 2-host version of umlXhost. The "EAST" and "WEST" slots are defined. +</P> + +<H2 NAME="umlXhost">umlXhost parameters</H2> +<P> +The umlXtest function starts an arbitrary number of user mode line processes. +</P> + +<!-- <IMG SRC="single_netjig.png" ALT="block diagram of uml_netjig"> --> + +<P> +The script invoked (<CODE>testing/utils/Xhost-test.tcl</CODE>) is a TCL +<A HREF="http://expect.nist.gov/">expect</A> script that arranges to start each +UML +and configure it appropriately for the test. It then starts listening +(using uml_netjig) to the simulated network answering ARPs and +inserting packets as appropriate. +</P> + +<P> +umlXtest has a series of slots, each of which should be filled by a host. +The list of slots is controlled by the variable, XHOST_LIST. This variable +should be set to a space seperated list of slots. The former umlplutotest +is now implemented as a variation of the umlXhost test, +with XHOST_LIST="EAST WEST". +</P> + +<P> +For each host slot that is defined, a series of variables should be +filled in, defining what configuration scripts to use for that host. +</P> + +<P> +The following are used to control the console input and output to the system. +Where the string ${host} is present, the host slot should be filled in. +I.e. for the two host system with XHOST_LIST="EAST WEST", then the +variables: EAST_INIT_SCRIPT and WEST_INIT_SCRIPT will exist. +<DL> +<DT>${host}HOST</DT> +<DD>The name of the UML host which will fill this slot</DD> +<DT>${host}_INIT_SCRIPT</DT> +<DD><p>a file of commands that is fed into the virtual machine's console + in single user mode prior to starting the tests. This file will + usually set up any eroute's and SADB entries that are required for + the test. Similar to INIT_SCRIPT, above.</p> +<DT>${host}_RUN_SCRIPT</DT> +<DD><P>a file of commands that is fed into the virtual machine's console + in single user mode, before the packets are sent. This set of + commands is run after all of the virtual machines are initialized. + I.e. after EAST_INIT_SCRIPT <B>AND</B> WEST_INIT_SCRIPT. This script + can therefore do things that require that all machines are properly + configured.</P> +<DT>${host}_RUN2_SCRIPT</DT> +<DD><P>a file of commands that is fed into the virtual machine's console + in single user mode, after the packets are sent. This set of + commands is run before any of the virtual machines have been shut + down. (I.e. before EAST_FINAL_SCRIPT <B>AND</B> WEST_FINAL_SCRIPT.) + This script can therefore catch post-activity status reports.</P> +<DT>${host}_FINAL_SCRIPT</DT> +<DD><p>a file of commands that is fed into the virtual machine's console + in single user mode after the final packet is sent. Similar to INIT_SCRIPT, + above. If not specified, then the single command "halt" is sent. Note that + when this script is run, the other virtual machines may already have been killed. + If specified, then the script should end with a halt command to nicely + shutdown the UML. +</P> +<DT>REF_${host}_CONSOLE_OUTPUT</DT> +<DD>Similar to REF_CONSOLE_OUTPUT, above.</DT> +</DL> +</P> + +<P>Some additional flags apply to all hosts: +<DL> +<DT>REF_CONSOLE_FIXUPS</DT> +<DD>a list of scripts (found in <CODE>klips/test/fixups</CODE>) to + apply to sanitize the console output of the machine under test. + These are typically perl, awk or sed scripts that remove things in + the kernel output that change each time the test is run and/or + compiled. +</DD> +</DL> +</P> + +<P> In addition to input to the console, the networks may have input +fed to them: +<DL> +<DT>EAST_INPUT/WEST_INPUT</DT> +<DD>a <A HREF="http://www.tcpdump.org/">pcap</A> file to feed in on + the private network side of each network. The "EAST" and "WEST" here +refer to the networks, not the hosts.</DD> +<DT>REF_PUB_FILTER</DT> +<DD>a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".</DD> +<DT>REF_EAST_FILTER/REF_WEST_FILTER</DT> +<DD>a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".</DD>< +<DT>TCPDUMPFLAGS</DT> +<DD>a set of flags for the tcpdump used when converting captured + output. Typical values will include "-n" to turn off DNS, and often + "-E" to set the decryption key (tcpdump 3.7.1 and higher only) for + ESP packets. The "-t" flag (turn off timestamps) is provided automatically</DD> +<DT>REF_EAST_OUTPUT/REF_WEST_OUTPUT</DT> +<DD>a text file containing tcpdump output. Packets on the private + (eth0) interface are captured and compared after conversion by + tcpdump, as with <VAR>REF_PUB_OUTPUT</VAR>.</DD> +</P> + +<P> +There are two additional environment variables that may be set on the +command line: +<DL> +<DT> NETJIGVERBOSE=verbose export NETJIGVERBOSE</DT> +<DD> If set, then the test output will be "chatty", and let you know what + commands it is running, and as packets are sent. Without it set, the + output is limited to success/failure messages.</DD> +<DT> NETJIGTESTDEBUG=netjig export NETJIGTESTDEBUG</DT> +<DD> This will enable debugging of the communication with uml_netjig, + and turn on debugging in this utility. + This does not imply NETJIGVERBOSE.</DL> +<DT> HOSTTESTDEBUG=hosttest export HOSTTESTDEBUG</DT> +<DD> This will show all interactions with the user-mode-linux + consoles</DD> +</DL> +</P> + +<H2 NAME="kernelpatch">kernel_patch_test paramaters</H2> +<P> +The kernel_patch_test function takes some kernel source, copies it with +lndir, and then applies the patch as produced by "make kernelpatch". +</P> +<P> +The following are used to control the input and output to the system: +<DL> +<DT>KERNEL_NAME</DT> +<DD>the kernel name, typically something like "linus" or "rh"</DD> +<DT>KERNEL_VERSION</DT> +<DD>the kernel version number, as in "2.2" or "2.4".</DD> +<DT>KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC</DT> +<DD>This variable should set in the environment, probably in + ~/freeswan-regress-env.sh. Examples of this variables would be + KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point + to an extracted copy of the kernel source in question.</DD> +<DT>REF_PATCH_OUTPUT</DT> +<DD>a copy of the patch output to compare against</DD> +<DT>KERNEL_PATCH_LEAVE_SOURCE</DT> +<DD>If set to a non-empty string, then the patched kernel source is not + removed at the end of the test. This will typically be set in the + environment while debugging.</DD> +</DL> +</P> + +<H2 NAME="modtest">module_compile paramaters</H2> +<P> +The module_compile test attempts to build the KLIPS module against a +given set of kernel source. This is also done by the RPM tests, but +in a very specific manner. +</P> +<P> +There are two variations of this test - one where the kernel either +doesn't need to be configured, or is already done, and tests were there +is a local configuration file. +</P> +<P> +Where the kernel doesn't need to be configured, the kernel source that +is found is simply used. It may be a RedHat-style kernel, where one +can cause it to configure itself via rhconfig.h-style definitions. Or, +it may just be a kernel tree that has been configured. +</P> +<P> +If the variable KERNEL_CONFIG_FILE is set, then a new directory is +created for the kernel source. It is populated with lndir(1). The referenced +file is then copied in as .config, and "make oldconfig" is used to configure +the kernel. This resulting kernel is then used as the reference source. +</P> +<p> +In all cases, the kernel source is found the same was for the kernelpatch +test, i.e. via KERNEL_VERSION/KERNEL_NAME and KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC.</P> +<P> +Once there is kernel source, the module is compiled using the top-level +"make module" target. +</P> +<P> +The test is considered successful if an executable is found in OUTPUT/module/ipsec.o at the end of the test. +</P> +<DL> +<DT>KERNEL_NAME</DT> +<DD>the kernel name, typically something like "linus" or "rh"</DD> +<DT>KERNEL_VERSION</DT> +<DD>the kernel version number, as in "2.2" or "2.4".</DD> +<DT>KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC</DT> +<DD>This variable should set in the environment, probably in + ~/freeswan-regress-env.sh. Examples of this variables would be + KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point + to an extracted copy of the kernel source in question.</DD> +<DT>KERNEL_CONFIG_FILE</DT> +<DD>The configuration file for the kernel.</DD> +<DT>KERNEL_PATCH_LEAVE_SOURCE</DT> +<DD>If set to a non-empty string, then the configured kernel source is not + removed at the end of the test. This will typically be set in the + environment while debugging.</DD> +<DT>MODULE_DEF_INCLUDE</DT> +<DD>The include file that will be used to configure the KLIPS module, and + possibly the kernel source. </DD> +</DL> + +<H1>Current pitfalls</H1> + +<DL> +<DT> "tcpdump dissector" not available. </DT> +<DD> This is a non-fatal warning. If uml_netjig is invoked with the -t + option, then it will attempt to use tcpdump's dissector to decode + each packet that it processes. The dissector is presently not + available, so this option it normally turned off at compile time. + The dissector library will be released with tcpdump version + 4.0.</DD> +</DL> + +</body> +</html>
\ No newline at end of file diff --git a/doc/src/manpages.html b/doc/src/manpages.html new file mode 100644 index 000000000..27a9aa7b3 --- /dev/null +++ b/doc/src/manpages.html @@ -0,0 +1,155 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN man pages</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, manpage, manual, page"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: manpages.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="manpages">FreeS/WAN manual pages</a></h1> + +<p>The various components of Linux FreeS/WAN are of course documented in +standard Unix manual pages, accessible via the man(1) command.</p> + +<p>Links here take you to an HTML version of the man pages.</p> + +<h2><a name="man.file">Files</a></h2> +<dl> + <dt><a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a></dt> + <dd>IPsec configuration and connections</dd> + <dt><a href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a></dt> + <dd>secrets for IKE authentication, either pre-shared keys or RSA private + keys</dd> +</dl> + +<p>These files are also discussed in the <a +href="config.html">configuration</a> section.</p> + +<h2><a name="man.command">Commands</a></h2> + +<p>Many users will never give most of the FreeS/WAN commands directly. +Configure the files listed above correctly and everything should be +automatic.</p> + +<p>The exceptions are commands for mainpulating the <a +href="glossary.html#RSA">RSA</a> keys used in Pluto authentication:</p> +<dl> + <dt><a href="manpage.d/ipsec_rsasigkey.8.html">ipsec_rsasigkey(8)</a></dt> + <dd>generate keys</dd> + <dt><a href="manpage.d/ipsec_newhostkey.8.html">ipsec_newhostkey(8)</a></dt> + <dd>generate keys in a convenient format</dd> + <dt><a + href="manpage.d/ipsec_showhostkey.8.html">ipsec_showhostkey(8)</a></dt> + <dd>extract <a href="glossary.html#RSA">RSA</a> keys from <a + href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</a> (or + optionally, another file) and format them for insertion in <a + href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a> or in DNS + records</dd> +</dl> + +<p>Note that:</p> +<ul> + <li>These keys are for <strong>authentication only</strong>. They are + <strong>not secure for encryption</strong>.</li> + <li>The utility uses random(4) as a source of <a + href="glossary.html#random">random numbers</a>. This may block for some + time if there is not enough activity on the machine to provide the + required entropy. You may want to give it some bogus activity such as + random mouse movements or some command such as <nobr><tt>du /usr > /dev/null + &</tt></nobr>.</li> +</ul> + +<p>The following commands are fairly likely to be used, if only for testing +and status checks:</p> +<dl> + <dt><a href="manpage.d/ipsec.8.html">ipsec(8)</a></dt> + <dd>invoke IPsec utilities</dd> + <dt><a href="manpage.d/ipsec_setup.8.html">ipsec_setup(8)</a></dt> + <dd>control IPsec subsystem</dd> + <dt><a href="manpage.d/ipsec_auto.8.html">ipsec_auto(8)</a></dt> + <dd>control automatically-keyed IPsec connections</dd> + <dt><a href="manpage.d/ipsec_manual.8.html">ipsec_manual(8)</a></dt> + <dd>take manually-keyed IPsec connections up and down</dd> + <dt><a href="manpage.d/ipsec_ranbits.8.html">ipsec_ranbits(8)</a></dt> + <dd>generate random bits in ASCII form</dd> + <dt><a href="manpage.d/ipsec_look.8.html">ipsec_look(8)</a></dt> + <dd>show minimal debugging information</dd> + <dt><a href="manpage.d/ipsec_barf.8.html">ipsec_barf(8)</a></dt> + <dd>spew out collected IPsec debugging information</dd> +</dl> + +<p>The lower-level utilities listed below are normally invoked via scripts +listed above, but they can also be used directly when required.</p> +<dl> + <dt><a href="manpage.d/ipsec_eroute.8.html">ipsec_eroute(8)</a></dt> + <dd>manipulate IPsec extended routing tables</dd> + <dt><a href="manpage.d/ipsec_klipsdebug.8.html">ipsec_klipsdebug(8)</a></dt> + <dd>set Klips (kernel IPsec support) debug features and level</dd> + <dt><a href="manpage.d/ipsec_pluto.8.html">ipsec_pluto(8)</a></dt> + <dd>IPsec IKE keying daemon</dd> + <dt><a href="manpage.d/ipsec_spi.8.html">ipsec_spi(8)</a></dt> + <dd>manage IPsec Security Associations</dd> + <dt><a href="manpage.d/ipsec_spigrp.8.html">ipsec_spigrp(8)</a></dt> + <dd>group/ungroup IPsec Security Associations</dd> + <dt><a href="manpage.d/ipsec_tncfg.8.html">ipsec_tncfg(8)</a></dt> + <dd>associate IPsec virtual interface with real interface</dd> + <dt><a href="manpage.d/ipsec_whack.8.html">ipsec_whack(8)</a></dt> + <dd>control interface for IPsec keying daemon</dd> +</dl> + +<h2><a name="man.lib">Library routines</a></h2> +<dl> + <dt><a href="manpage.d/ipsec_atoaddr.3.html">ipsec_atoaddr(3)</a></dt> + <dt><a href="manpage.d/ipsec_addrtoa.3.html">ipsec_addrtoa(3)</a></dt> + <dd>convert Internet addresses to and from ASCII</dd> + <dt><a href="manpage.d/ipsec_atosubnet.3.html">ipsec_atosubnet(3)</a></dt> + <dt><a href="manpage.d/ipsec_subnettoa.3.html">ipsec_subnettoa(3)</a></dt> + <dd>convert subnet/mask ASCII form to and from addresses</dd> + <dt><a href="manpage.d/ipsec_atoasr.3.html">ipsec_atoasr(3)</a></dt> + <dd>convert ASCII to Internet address, subnet, or range</dd> + <dt><a href="manpage.d/ipsec_rangetoa.3.html">ipsec_rangetoa(3)</a></dt> + <dd>convert Internet address range to ASCII</dd> + <dt>ipsec_atodata(3)</dt> + <dt><a href="manpage.d/ipsec_datatoa.3.html">ipsec_datatoa(3)</a></dt> + <dd>convert binary data from and to ASCII formats</dd> + <dt><a href="manpage.d/ipsec_atosa.3.html">ipsec_atosa(3)</a></dt> + <dt><a href="manpage.d/ipsec_satoa.3.html">ipsec_satoa(3)</a></dt> + <dd>convert IPsec Security Association IDs to and from ASCII</dd> + <dt><a href="manpage.d/ipsec_atoul.3.html">ipsec_atoul(3)</a></dt> + <dt><a href="manpage.d/ipsec_ultoa.3.html">ipsec_ultoa(3)</a></dt> + <dd>convert unsigned-long numbers to and from ASCII</dd> + <dt><a href="manpage.d/ipsec_goodmask.3.html">ipsec_goodmask(3)</a></dt> + <dd>is this Internet subnet mask a valid one?</dd> + <dt><a href="manpage.d/ipsec_masktobits.3.html">ipsec_masktobits(3)</a></dt> + <dd>convert Internet subnet mask to bit count</dd> + <dt><a href="manpage.d/ipsec_bitstomask.3.html">ipsec_bitstomask(3)</a></dt> + <dd>convert bit count to Internet subnet mask</dd> + <dt><a + href="manpage.d/ipsec_optionsfrom.3.html">ipsec_optionsfrom(3)</a></dt> + <dd>read additional ``command-line'' options from file</dd> + <dt><a href="manpage.d/ipsec_subnetof.3.html">ipsec_subnetof(3)</a></dt> + <dd>given Internet address and subnet mask, return subnet number</dd> + <dt><a href="manpage.d/ipsec_hostof.3.html">ipsec_hostof(3)</a></dt> + <dd>given Internet address and subnet mask, return host part</dd> + <dt><a + href="manpage.d/ipsec_broadcastof.3.html">ipsec_broadcastof(3)</a></dt> + <dd>given Internet address and subnet mask, return broadcast address</dd> +</dl> +</body> +</html> diff --git a/doc/src/nightly.html b/doc/src/nightly.html new file mode 100644 index 000000000..d86037884 --- /dev/null +++ b/doc/src/nightly.html @@ -0,0 +1,164 @@ +<html> +<head> +<title>FreeS/WAN nightly testing guide</title> +<!-- Changed by: Michael Richardson, 23-Jul-2002 --> +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, testing, User-Mode-Linux, UML"> + +<!-- + +Written by Michael Richardson for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +$Id: nightly.html,v 1.1 2004/03/15 20:35:24 as Exp $ + +$Log: nightly.html,v $ +Revision 1.1 2004/03/15 20:35:24 as +added files from freeswan-2.04-x509-1.5.3 + +Revision 1.3 2002/07/23 18:42:16 mcr + added instructions on setup of nightly build. + +Revision 1.2 2002/06/19 10:06:07 mcr + added nightly.html to the documentation tree. + +Revision 1.1 2002/05/24 03:33:30 mcr + start at document on nightly regression testing. + + +--> +</head> + +<body> + +<h1><a name="nightly">Nightly regression testing</a></h1> + +<p> +The nightly regression testing system consists of several shell scripts +and some perl scripts. The goal is to check out a fresh tree, run "make check" on it, +record the results and summarize the results to the team and to the web site. +</p> + +<P> +Output can be found on <A HREF="http://bugs.freeswan.org:81/">adams</A>, +although the tests are actually run on another project machine.</P> + +<H1><A name="nightlyhowto">How to setup the nightly build</A></h1> + +<P> +The best way to do nightly testing is to setup a new account. We call the +account "build" - you could call it something else, but there may +still be some references to ~build in the scripts. +</P> + +<H2> Files you need to know about </H2> +<P> +As few files as possible need to be extracted from the source tree - +files are run from the source tree whenever possible. However, there +are some bootstrap and configuration files that are necessary. +</P> + +<P> +There are 7 files in testing/utils that are involved: +<DL> +<DT> nightly-sample.sh </DT> +<DD> This is the root of the build process. This file should be copied out +of the CVS tree, to $HOME/bin/nightly.sh of the build account. This +file should be invoked from cron. </DD> +<DT> freeswan-regress-env-sample.sh </DT> +<DD> This file should be copied to $HOME/freeswan-regress-env.sh. It + should be edited to localize the values. See below.</DD> +<DT> regress-cleanup.pl </DT> +<DD> This file needs to be copied to $HOME/bin/regress-cleanup.pl. It + is invoked by the nightly file before doing anything else. It + removes previous nights builds in order to free up disk space for + the build about to be done.</DD> +<DT> teammail-sample.sh </DT> +<DD> A script used to send results email to the "team". This sample + script could be copied to $HOME/bin/teammail.sh. This version will + PGP encrypt all the output to the team members. If this script is used, + then PGP will have to be properly setup to have the right keys.</DD> +<DT> regress-nightly.sh </DT> +<DD> This is the first stage of the nightly build. This stage will + call other scripts as appropriate, and will extract the source code + from CVS. This script should be copied to $HOME/bin/regress-nightly.sh</DD> +<DT> regress-stage2.sh </DT> +<DD> This is the second stage of the nightly build. It is called in + place. It essentially sets up the UML setup in umlsetup.sh, and + calls "make check".</DD> +<DT> regress-summarize-results.pl +<DD> This script will summarize the results from the tests to a + permanent directory set by $REGRESSRESULTS. It is invoked from the + stage2 nightly script. +<DT> regress-chart.sh </DT> +<DD> This script is called at the end of the build process, and will + summarize each night's results (as saved into $REGRESSRESULTS by + regress-summarize-results.pl) as a chart using gnuplot. Note that + this requires at least gnuplot 3.7.2.</DD> +</DL> + +<H2>Configuring freeswan-regress-env.sh</H2> + +<P>For more info on KERNPOOL, UMLPATCH, BASICROOT and SHAREDIR, see + <A HREF="umltesting.html">User-Mode-Linux testing guide</A>. +</P> + +<DL> +<DT> KERNPOOL </DT> +<DD> Extract copy of some kernel source to be used for UML builds</DD> +<DT> UMLPATCH </DT> +<DD> matching User-Mode-Linux patch.</DD> +<DT> BASICROOT</DT> +<DD> the root file system image (see + <A HREF="umltesting.html">User-Mode-Linux testing guide</A>).</DD> +<DT> SHAREDIR=${BASICROOT}/usr/share</DT> +<DD> The /usr/share to use.</DD> +<DT> REGRESSTREE</DT> +<DD> A directory in which to store the nightly regression + results. Directories will be created by date in this tree.</DD> + +<DT> TCPDUMP=tcpdump-3.7.1</DT> +<DD> The path to the <A HREF="http://www.tcpdump.org/">tcpdump</A> + to use. This must have crypto compiled in, and must be at least 3.7.1</DT> + +<DT> KERNEL_RH7_2_SRC=/a3/kernel_sources/linux-2.4.9-13/</DT> +<DD> An extracted copy of the RedHat 7.2. kernel source. If set, then + the packaging/rpm-rh72-install-01 test will be run, and an RPM will + be built as a test.</DD> + +<DT> KERNEL_RH7_3_SRC=/a3/kernel_sources/rh/linux-2.4.18-5</DT> +<DD> An extracted copy of the RedHat 7.3. kernel source. If set, then + the packaging/rpm-rh73-install-01 test will be run, and an RPM will + be built as a test.</DD> + +<DT> NIGHTLY_WATCHERS="userid,userid,userid"</DT> +<DD> The list of people who should receive nightly output. This is + used by teammail.sh</DD> + +<DT> FAILLINES=128</DT> +<DD> How many lines of failed test output to include in the nightly + output</DD> + +<DT> PATH=$PATH:/sandel/bin export PATH</DT> +<DD> You can also override the path if necessary here.</DD> + +<DT> CVSROOT=:pserver:anoncvs@ip212.xs4net.freeswan.org:/freeswan/MASTER</DT> +<DD> The CVSROOT to use. This example may work for anonymous CVS, but + will be 12 hours behind the primary, and is still experimental</DD> + +<DT> SNAPSHOTSIGDIR=$HOME/snapshot-sig</DT> +<DD> For the release tools, where to put the generated per-snapshot + signature keys</DD> + +<DT> LASTREL=1.97</DT> +<DD> the name of the last release branch (to find the right + per-snapshot signature</DT> + +<DD> + +</DL> + +</body> +</html>
\ No newline at end of file diff --git a/doc/src/performance.html b/doc/src/performance.html new file mode 100755 index 000000000..9d90acc62 --- /dev/null +++ b/doc/src/performance.html @@ -0,0 +1,576 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN performance</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, performance, benchmark"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: performance.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="performance">Performance of FreeS/WAN</a></h1> +The performance of FreeS/WAN is adequate for most applications. + +<p>In normal operation, the main concern is the overhead for encryption, +decryption and authentication of the actual IPsec (<a +href="glossary.html#ESP">ESP</a> and/or <a href="glossary.html#AH">AH</a>) +data packets. Tunnel setup and rekeying occur so much less frequently than +packet processing that, in general, their overheads are not worth worrying +about.</p> + +<p>At startup, however, tunnel setup overheads may be significant. If you +reboot a gateway and it needs to establish many tunnels, expect some delay. +This and other issues for large gateways are discussed <a +href="#biggate">below</a>.</p> + +<h2><a name="pub.bench">Published material</a></h2> + +<p>The University of Wales at Aberystwyth has done quite detailed speed tests +and put <a href="http://tsc.llwybr.org.uk/public/reports/SWANTIME/">their +results</a> on the web.</p> + +<p>Davide Cerri's <a href="http://www.linux.it/~davide/doc/">thesis (in +Italian)</a> includes performance results for FreeS/WAN and for <a +href="glossary.html#TLS">TLS</a>. He posted an <a +href="http://lists.freeswan.org/pipermail/users/2001-December/006303.html">English +summary</a> on the mailing list.</p> + +<p>Steve Bellovin used one of AT&T Research's FreeS/WAN gateways as his +data source for an analysis of the cache sizes required for key swapping in +IPsec. Available as <a +href="http://www.research.att.com/~smb/talks/key-agility.email.txt">text</a> +or <a href="http://www.research.att.com/~smb/talks/key-agility.pdf">PDF +slides</a> for a talk on the topic.</p> + +<p>See also the NAI work mentioned in the next section.</p> + +<h2><a name="perf.estimate">Estimating CPU overheads</a></h2> + +<p>We can come up with a formula that roughly relates CPU speed to the rate +of IPsec processing possible. It is far from exact, but should be usable as a +first approximation.</p> + +<p>An analysis of authentication overheads for high-speed networks, including +some tests using FreeS/WAN, is on the <a +href="http://www.pgp.com/research/nailabs/cryptographic/adaptive-cryptographic.asp">NAI +Labs site</a>. In particular, see figure 3 in this <a +href="http://download.nai.com/products/media/pgp/pdf/acsa_final_report.pdf">PDF +document</a>. Their estimates of overheads, measured in Pentium II cycles per +byte processed are:</p> + +<table border="1" align="center"> + <tbody> + <tr> + <th></th> + <th>IPsec</th> + <th>authentication</th> + <th>encryption</th> + <th>cycles/byte</th> + </tr> + <tr> + <td>Linux IP stack alone</td> + <td>no</td> + <td>no</td> + <td>no</td> + <td align="right">5</td> + </tr> + <tr> + <td>IPsec without crypto</td> + <td>yes</td> + <td>no</td> + <td>no</td> + <td align="right">11</td> + </tr> + <tr> + <td>IPsec, authentication only</td> + <td>yes</td> + <td>SHA-1</td> + <td>no</td> + <td align="right">24</td> + </tr> + <tr> + <td>IPsec with encryption</td> + <td>yes</td> + <td>yes</td> + <td>yes</td> + <td align="right">not tested</td> + </tr> + </tbody> +</table> + +<p>Overheads for IPsec with encryption were not tested in the NAI work, but +Antoon Bosselaers' <a +href="http://www.esat.kuleuven.ac.be/~bosselae/fast.html">web page</a> gives +cost for his optimised Triple DES implementation as 928 Pentium cycles per +block, or 116 per byte. Adding that to the 24 above, we get 140 cycles per +byte for IPsec with encryption.</p> + +<p>At 140 cycles per byte, a 140 MHz machine can handle a megabyte -- 8 +megabits -- per second. Speeds for other machines will be proportional to +this. To saturate a link with capacity C megabits per second, you need a +machine running at <var>C * 140/8 = C * 17.5</var> MHz.</p> + +<p>However, that estimate is not precise. It ignores the differences +between:</p> +<ul> + <li>NAI's test packets and real traffic</li> + <li>NAI's Pentium II cycles, Bosselaers' Pentium cycles, and your machine's + cycles</li> + <li>different 3DES implementations</li> + <li>SHA-1 and MD5</li> +</ul> + +<p>and does not account for some overheads you will almost certainly have:</p> +<ul> + <li>communication on the client-side interface</li> + <li>switching between multiple tunnels -- re-keying, cache reloading and so + on</li> +</ul> + +<p>so we suggest using <var>C * 25</var> to get an estimate with a bit of a +built-in safety factor.</p> + +<p>This covers only IP and IPsec processing. If you have other loads on your +gateway -- for example if it is also working as a firewall -- then you will +need to add your own safety factor atop that.</p> + +<p>This estimate matches empirical data reasonably well. For example, +Metheringham's tests, described <a href="#klips.bench">below</a>, show a 733 +topping out between 32 and 36 Mbit/second, pushing data as fast as it can +down a 100 Mbit link. Our formula suggests you need at least an 800 to handle +a fully loaded 32 Mbit link. The two results are consistent.</p> + +<p>Some examples using this estimation method:</p> + +<table border="1" align="center"> + <tbody> + <tr> + <th colspan="2">Interface</th> + <th colspan="3">Machine speed in MHz</th> + </tr> + <tr> + <th>Type</th> + <th>Mbit per<br> + second</th> + <th>Estimate<br> + Mbit*25</th> + <th>Minimum IPSEC gateway</th> + <th>Minimum with other load + + <p>(e.g. firewall)</p> + </th> + </tr> + <tr> + <td>DSL</td> + <td align="right">1</td> + <td align="right">25 MHz</td> + <td rowspan="2">whatever you have</td> + <td rowspan="2">133, or better if you have it</td> + </tr> + <tr> + <td>cable modem</td> + <td align="right">3</td> + <td align="right">75 MHz</td> + </tr> + <tr> + <td><strong>any link, light load</strong></td> + <td align="right"><strong>5</strong></td> + <td align="right">125 MHz</td> + <td>133</td> + <td>200+, <strong>almost any surplus machine</strong></td> + </tr> + <tr> + <td>Ethernet</td> + <td align="right">10</td> + <td align="right">250 MHz</td> + <td>surplus 266 or 300</td> + <td>500+</td> + </tr> + <tr> + <td><strong>fast link, moderate load</strong></td> + <td align="right"><strong>20</strong></td> + <td align="right">500 MHz</td> + <td>500</td> + <td>800+, <strong>any current off-the-shelf PC</strong></td> + </tr> + <tr> + <td>T3 or E3</td> + <td align="right">45</td> + <td align="right">1125 MHz</td> + <td>1200</td> + <td>1500+</td> + </tr> + <tr> + <td>fast Ethernet</td> + <td align="right">100</td> + <td align="right">2500 MHz</td> + <td rowspan="2" colspan="2" align="center">// not feasible with 3DES in + software on current machines //</td> + </tr> + <tr> + <td>OC3</td> + <td align="right">155</td> + <td align="right">3875 MHz</td> + </tr> + </tbody> +</table> + +<p>Such an estimate is far from exact, but should be usable as minimum +requirement for planning. The key observations are:</p> +<ul> + <li>older <strong>surplus machines</strong> are fine for IPsec gateways at + loads up to <strong>5 megabits per second</strong> or so</li> + <li>a <strong>mid-range new machine</strong> can handle IPsec at rates up + to <strong>20 megabits per second</strong> or more</li> +</ul> + <h3><a name="perf.more">Higher performance alternatives</a></h3> + + <p><a href="glossary.html#AES">AES</a> is a new US government block cipher + standard, designed to replace the obsolete <a + href="glossary.html#DES">DES</a>. If FreeS/WAN using <a + href="glossary.html#3DES">3DES</a> is not fast enough for your application, + the AES <a href="web.html#patch">patch</a> may help.</p> + + <p>To date (March 2002) we have had only one <a + href="http://lists.freeswan.org/pipermail/users/2002-February/007771.html">mailing + list report</a> of measurements with the patch applied. It indicates that, + at least for the tested load on that user's network, <strong>AES roughly + doubles IPsec throughput</strong>. If further testing confirms this, it may + prove possible to saturate an OC3 link in software on a high-end box.</p> + + <p>Also, some work is being done toward support of <a + href="compat.html#hardware">hardware IPsec acceleration</a> which might + extend the range of requirements FreeS/WAN could meet.</p> + + <h3>Other considerations</h3> + + <p>CPU speed may be the main issue for IPsec performance, but of course it + isn't the only one.</p> + + <p>You need good ethernet cards or other network interface hardware to get + the best performance. See this <a + href="http://www.ethermanage.com/ethernet/ethernet.html">ethernet + information</a> page and this <a href="http://www.scyld.com/diag">Linux + network driver</a> page.</p> + + <p>The current FreeS/WAN kernel code is largely single-threaded. It is SMP + safe, and will run just fine on a multiprocessor machine (<a + href="compat.html#multiprocessor">discussion</a>), but the load within the + kernel is not shared effectively. This means that, for example to saturate + a T3 -- which needs about a 1200 MHz machine -- you cannot expect something + like a dual 800 to do the job. </p> + + <p>On the other hand, SMP machines do tend to share loads well so -- + provided one CPU is fast enough for the IPsec work -- a multiprocessor + machine may be ideal for a gateway with a mixed load.</p> + + <h2><a name="biggate">Many tunnels from a single gateway</a></h2> + + <p>FreeS/WAN allows a single gateway machine to build tunnels to many + others. There may, however, be some problems for large numbers as indicated + in this message from the mailing list:</p> + +<pre>Subject: Re: Maximum number of ipsec tunnels? + Date: Tue, 18 Apr 2000 + From: "John S. Denker" <jsd@research.att.com> + +Christopher Ferris wrote: + +>> What are the maximum number ipsec tunnels FreeS/WAN can handle?? + +Henry Spencer wrote: + +>There is no particular limit. Some of the setup procedures currently +>scale poorly to large numbers of connections, but there are (clumsy) +>workarounds for that now, and proper fixes are coming. + +1) "Large" numbers means anything over 50 or so. I routinely run boxes +with about 200 tunnels. Once you get more than 50 or so, you need to worry +about several scalability issues: + +a) You need to put a "-" sign in syslogd.conf, and rotate the logs daily +not weekly. + +b) Processor load per tunnel is small unless the tunnel is not up, in which +case a new half-key gets generated every 90 seconds, which can add up if +you've got a lot of down tunnels. + +c) There's other bits of lore you need when running a large number of +tunnels. For instance, systematically keeping the .conf file free of +conflicts requires tools that aren't shipped with the standard freeswan +package. + +d) The pluto startup behavior is quadratic. With 200 tunnels, this eats up +several minutes at every restart. I'm told fixes are coming soon. + +2) Other than item (1b), the CPU load depends mainly on the size of the +pipe attached, not on the number of tunnels. +</pre> + +<p>It is worth noting that item (1b) applies only to repeated attempts to +re-key a data connection (IPsec SA, Phase 2) over an established keying +connection (ISAKMP SA, Phase 1). There are two ways to reduce this overhead +using settings in <a href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</a>:</p> +<ul> + <li>set <var>keyingtries</var> to some small value to limit repetitions</li> + <li>set <var>keylife</var> to a short time so that a failing data + connection will be cleaned up when the keying connection is reset.</li> +</ul> + +<p>The overheads for establishing keying connections (ISAKMP SAs, Phase 1) +are lower because for these Pluto does not perform expensive operations +before receiving a reply from the peer.</p> + +<p>A gateway that does a lot of rekeying -- many tunnels and/or low settings +for tunnel lifetimes -- will also need a lot of <a +href="glossary.html#random">random numbers</a> from the random(4) driver.</p> + +<h2><a name="low-end">Low-end systems</a></h2> + +<p><em>Even a 486 can handle a T1 line</em>, according to this mailing list +message:</p> +<pre>Subject: Re: linux-ipsec: IPSec Masquerade + Date: Fri, 15 Jan 1999 11:13:22 -0500 + From: Michael Richardson + +. . . A 486/66 has been clocked by Phil Karn to do +10Mb/s encryption.. that uses all the CPU, so half that to get some CPU, +and you have 5Mb/s. 1/3 that for 3DES and you get 1.6Mb/s....</pre> + +<p>and a piece of mail from project technical lead Henry Spencer:</p> +<pre>Oh yes, and a new timing point for Sandy's docs... A P60 -- yes, a 60MHz +Pentium, talk about antiques -- running a host-to-host tunnel to another +machine shows an FTP throughput (that is, end-to-end results with a real +protocol) of slightly over 5Mbit/s either way. (The other machine is much +faster, the network is 100Mbps, and the ether cards are good ones... so +the P60 is pretty definitely the bottleneck.)</pre> + +<p>From the above, and from general user experience as reported on the list, +it seems clear that a cheap surplus machine -- a reasonable 486, a minimal +Pentium box, a Sparc 5, ... -- can easily handle a home office or a small +company connection using any of:</p> +<ul> + <li>ADSL service</li> + <li>cable modem</li> + <li>T1</li> + <li>E1</li> +</ul> + +<p>If available, we suggest using a Pentium 133 or better. This should ensure +that, even under maximum load, IPsec will use less than half the CPU cycles. +You then have enough left for other things you may want on your gateway -- +firewalling, web caching, DNS and such.</p> + +<h2><a name="klips.bench">Measuring KLIPS</a></h2> + +<p>Here is some additional data from the mailing list.</p> +<pre>Subject: FreeSWAN (specically KLIPS) performance measurements + Date: Thu, 01 Feb 2001 + From: Nigel Metheringham <Nigel.Metheringham@intechnology.co.uk> + +I've spent a happy morning attempting performance tests against KLIPS +(this is due to me not being able to work out the CPU usage of KLIPS so +resorting to the crude measurements of maximum throughput to give a +baseline to work out loading of a box). + +Measurements were done using a set of 4 boxes arranged in a line, each +connected to the next by 100Mbit duplex ethernet. The inner 2 had an +ipsec tunnel between them (shared secret, but I was doing measurements +when the tunnel was up and running - keying should not be an issue +here). The outer pair of boxes were traffic generators or traffic sink. + +The crypt boxes are Compaq DL380s - Uniprocessor PIII/733 with 256K +cache. They have 128M main memory. Nothing significant was running on +the boxes other than freeswan. The kernel was a 2.2.19pre7 patched +with freeswan and ext3. + +Without an ipsec tunnel in the chain (ie the 2 inner boxes just being +100BaseT routers), throughput (measured with ttcp) was between 10644 +and 11320 KB/sec + +With an ipsec tunnel in place, throughput was between 3268 and 3402 +KB/sec + +These measurements are for data pushed across a TCP link, so the +traffic on the wire between the 2 ipsec boxes would have been higher +than this.... + +vmstat (run during some other tests, so not affecting those figures) on +the encrypting box shows approx 50% system & 50% idle CPU - which I +don't believe at all. Interactive feel of the box was significantly +sluggish. + +I also tried running the kernel profiler (see man readprofile) during +test runs. + +A box doing primarily decrypt work showed basically nothing happening - +I assume interrupts were off. +A box doing encrypt work showed the following:- + Ticks Function Load + ~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~ + 956 total 0.0010 + 532 des_encrypt2 0.1330 + 110 MD5Transform 0.0443 + 97 kmalloc 0.1880 + 39 des_encrypt3 0.1336 + 23 speedo_interrupt 0.0298 + 14 skb_copy_expand 0.0250 + 13 ipsec_tunnel_start_xmit 0.0009 + 13 Decode 0.1625 + 11 handle_IRQ_event 0.1019 + 11 .des_ncbc_encrypt_end 0.0229 + 10 speedo_start_xmit 0.0188 + 9 satoa 0.0225 + 8 kfree 0.0118 + 8 ip_fragment 0.0121 + 7 ultoa 0.0365 + 5 speedo_rx 0.0071 + 5 .des_encrypt2_end 5.0000 + 4 _stext 0.0140 + 4 ip_fw_check 0.0035 + 2 rj_match 0.0034 + 2 ipfw_output_check 0.0200 + 2 inet_addr_type 0.0156 + 2 eth_copy_and_sum 0.0139 + 2 dev_get 0.0294 + 2 addrtoa 0.0143 + 1 speedo_tx_buffer_gc 0.0024 + 1 speedo_refill_rx_buf 0.0022 + 1 restore_all 0.0667 + 1 number 0.0020 + 1 net_bh 0.0021 + 1 neigh_connected_output 0.0076 + 1 MD5Final 0.0083 + 1 kmem_cache_free 0.0016 + 1 kmem_cache_alloc 0.0022 + 1 __kfree_skb 0.0060 + 1 ipsec_rcv 0.0001 + 1 ip_rcv 0.0014 + 1 ip_options_fragment 0.0071 + 1 ip_local_deliver 0.0023 + 1 ipfw_forward_check 0.0139 + 1 ip_forward 0.0011 + 1 eth_header 0.0040 + 1 .des_encrypt3_end 0.0833 + 1 des_decrypt3 0.0034 + 1 csum_partial_copy_generic 0.0045 + 1 call_out_firewall 0.0125 + +Hope this data is helpful to someone... however the lack of visibility +into the decrypt side makes things less clear</pre> + +<h2><a name="speed.compress">Speed with compression</a></h2> + +<p>Another user reported some results for connections with and without IP +compression:</p> +<pre>Subject: [Users] Speed with compression + Date: Fri, 29 Jun 2001 + From: John McMonagle <johnm@advocap.org> + +Did a couple tests with compression using the new 1.91 freeswan. + +Running between 2 sites with cable modems. Both using approximately +130 mhz pentium. + +Transferred files with ncftp. + +Compressed file was a 6mb compressed installation file. +Non compressed was 18mb /var/lib/rpm/packages.rpm + + Compressed vpn regular vpn +Compress file 42.59 kBs 42.08 kBs +regular file 110.84 kBs 41.66 kBs + +Load was about 0 either way. +Ping times were very similar a bit above 9 ms. + +Compression looks attractive to me.</pre> +Later in the same thread, project technical lead Henry Spencer added: +<pre>> is there a reason not to switch compression on? I have large gateway boxes +> connecting 3 connections, one of them with a measly DS1 link... + +Run some timing tests with and without, with data and loads representative +of what you expect in production. That's the definitive way to decide. +If compression is a net loss, then obviously, leave it turned off. If it +doesn't make much difference, leave it off for simplicity and hence +robustness. If there's a substantial gain, by all means turn it on. + +If both ends support compression and can successfully negotiate a +compressed connection (trivially true if both are FreeS/WAN 1.91), then +the crucial question is CPU cycles. + +Compression has some overhead, so one question is whether *your* data +compresses well enough to save you more CPU cycles (by reducing the volume +of data going through CPU-intensive encryption/decryption) than it costs +you. Last time I ran such tests on data that was reasonably compressible +but not deliberately contrived to be so, this generally was not true -- +compression cost extra CPU cycles -- so compression was worthwhile only if +the link, not the CPU, was the bottleneck. However, that was before the +slow-compression bug was fixed. I haven't had a chance to re-run those +tests yet, but it sounds like I'd probably see a different result. </pre> +The bug he refers to was a problem with the compression libraries that had us +using C code, rather than assembler, for compression. It was fixed before +1.91. + +<h2><a name="methods">Methods of measuring</a></h2> + +<p>If you want to measure the loads FreeS/WAN puts on a system, note that +tools such as top or measurements such as load average are more-or-less +useless for this. They are not designed to measure something that does most +of its work inside the kernel.</p> + +<p>Here is a message from FreeS/WAN kernel programmer Richard Guy Briggs on +this:</p> +<pre>> I have a batch of boxes doing Freeswan stuff. +> I want to measure the CPU loading of the Freeswan tunnels, but am +> having trouble seeing how I get some figures out... +> +> - Keying etc is in userspace so will show up on the per-process +> and load average etc (ie pluto's load) + +Correct. + +> - KLIPS is in the kernel space, and does not show up in load average +> I think also that the KLIPS per-packet processing stuff is running +> as part of an interrupt handler so it does not show up in the +> /proc/stat system_cpu or even idle_cpu figures + +It is not running in interrupt handler. It is in the bottom half. +This is somewhere between user context (careful, this is not +userspace!) and hardware interrupt context. + +> Is this correct, and is there any means of instrumenting how much the +> cpu is being loaded - I don't like the idea of a system running out of +> steam whilst still showing 100% idle CPU :-) + +vmstat seems to do a fairly good job, but use a running tally to get a +good idea. A one-off call to vmstat gives different numbers than a +running stat. To do this, put an interval on your vmstat command +line.</pre> +and another suggestion from the same thread: +<pre>Subject: Re: Measuring the CPU usage of Freeswan + Date: Mon, 29 Jan 2001 + From: Patrick Michael Kane <modus@pr.es.to> + +The only truly accurate way to accurately track FreeSWAN CPU usage is to use +a CPU soaker. You run it on an unloaded system as a benchmark, then start up +FreeSWAN and take the difference to determine how much FreeSWAN is eating. +I believe someone has done this in the past, so you may find something in +the FreeSWAN archives. If not, someone recently posted a URL to a CPU +soaker benchmark tool on linux-kernel.</pre> +</body> +</html> diff --git a/doc/src/policy-groups-table.html b/doc/src/policy-groups-table.html new file mode 100644 index 000000000..8e84809cf --- /dev/null +++ b/doc/src/policy-groups-table.html @@ -0,0 +1,297 @@ +<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + + <meta name="Author" content="Richard Guy Briggs"> + + <meta name="GENERATOR" content="Mozilla/4.78 [en] (X11; U; Linux 2.4.18 i686) [Netscape]"> + <title></title> +</head> + <body> +Policy Groups Table<br> +<br> +This table lists all the policy group combinations and expected packet flows.<br> +<br> +<br> + +<table border="1" cols="14" width="100%" nosave=""> + <tbody> + <tr> + <th bgcolor="#cccccc">policy</th> + <th bgcolor="#cccccc"><br> + </th> + <th bgcolor="#cccccc" colspan="2">none</th> + <th bgcolor="#cccccc" colspan="2">clear</th> + <th bgcolor="#cccccc" colspan="2">clear-or-private</th> + <th bgcolor="#cccccc" colspan="2">private-or-clear</th> + <th bgcolor="#cccccc" colspan="2">private</th> + <th bgcolor="#cccccc" colspan="2">block</th> + </tr> + <tr> + <th bgcolor="#cccccc"><br> + </th> + <th bgcolor="#cccccc">key?</th> + <th bgcolor="#cccccc">no</th> + <th bgcolor="#cccccc">yes</th> + <th bgcolor="#cccccc">no</th> + <th bgcolor="#cccccc">yes</th> + <th bgcolor="#cccccc">no</th> + <th bgcolor="#cccccc">yes</th> + <th bgcolor="#cccccc">no</th> + <th bgcolor="#cccccc">yes</th> + <th bgcolor="#cccccc">no</th> + <th bgcolor="#cccccc">yes</th> + <th bgcolor="#cccccc">no</th> + <th bgcolor="#cccccc">yes</th> + </tr> + <tr> + <th bgcolor="#cccccc" rowspan="2">none</th> + <th bgcolor="#cccccc">no</th> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + </tr> + <tr> + <th bgcolor="#cccccc">yes</th> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c,f?</td> + <td>c,f?</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + </tr> + <tr> + <th bgcolor="#cccccc" rowspan="2">clear</th> + <th bgcolor="#cccccc">no</th> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c,c(f?)</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + </tr> + <tr> + <th bgcolor="#cccccc">yes</th> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c,f?</td> + <td>c,f?</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + </tr> + <tr> + <th bgcolor="#cccccc" rowspan="2">clear-or-private</th> + <th bgcolor="#cccccc">no</th> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c,f?</td> + <td>c,c(f?)</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + <td>c,f</td> + </tr> + <tr> + <th bgcolor="#cccccc">yes</th> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c</td> + <td>c,f?</td> + <td>c,e</td> + <td>c,f</td> + <td>c,e</td> + <td>c,f</td> + <td>c,f</td> + </tr> + <tr> + <th bgcolor="#cccccc" rowspan="2">private-or-clear</th> + <th bgcolor="#cccccc">no</th> + <td>t,c</td> + <td>t,f?</td> + <td>t,c</td> + <td>t,f?</td> + <td>t,c</td> + <td>t,f?</td> + <td>t,f?</td> + <td>t,f?</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + </tr> + <tr> + <th bgcolor="#cccccc">yes</th> + <td>t,c</td> + <td>t,f?</td> + <td>t,c</td> + <td>t,f?</td> + <td>t,c</td> + <td>t,e</td> + <td>t,c(f?)</td> + <td>t,e</td> + <td>t,f</td> + <td>t,e</td> + <td>t,f</td> + <td>t,f</td> + </tr> + <tr> + <th bgcolor="#cccccc" rowspan="2">private</th> + <th bgcolor="#cccccc">no</th> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + </tr> + <tr> + <th bgcolor="#cccccc">yes</th> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,f</td> + <td>t,e</td> + <td>t,f</td> + <td>t,e</td> + <td>t,f</td> + <td>t,e</td> + <td>t,f</td> + <td>t,f</td> + </tr> + <tr> + <th bgcolor="#cccccc" rowspan="2">block</th> + <th bgcolor="#cccccc">no</th> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + </tr> + <tr> + <th bgcolor="#cccccc">yes</th> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + <td>f</td> + </tr> + + </tbody> +</table> + <br> + +<table border="1" cols="2" nosave=""> + <tbody> + <tr nosave=""> + <th nosave="">legend</th> + <th>packet fate</th> + </tr> + <tr> + <td>c</td> + <td>clear</td> + </tr> + <tr> + <td>f</td> + <td>fail</td> + </tr> + <tr> + <td>e</td> + <td>encrypt</td> + </tr> + <tr> + <td>t</td> + <td>trap</td> + </tr> + <tr> + <td valign="Top">c,f<br> + </td> + <td valign="Top">first packet clear, then fail<br> + </td> + </tr> + <tr> + <td valign="Top">c,e<br> + </td> + <td valign="Top">first packet clear, then encrypt<br> + </td> + </tr> + <tr> + <td valign="Top">t,f<br> + </td> + <td valign="Top">trap, then fail<br> + </td> + </tr> + <tr> + <td valign="Top">t,c<br> + </td> + <td valign="Top">trap, then clear<br> + </td> + </tr> + <tr> + <td valign="Top">t,e<br> + </td> + <td valign="Top">trap, then encrypt<br> + </td> + </tr> + + </tbody> +</table> + +</body> +</html> diff --git a/doc/src/policygroups.html b/doc/src/policygroups.html new file mode 100644 index 000000000..0425ade39 --- /dev/null +++ b/doc/src/policygroups.html @@ -0,0 +1,489 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>Configuring FreeS/WAN with policy groups</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, encryption, cryptography, FreeS/WAN, FreeSWAN"> + <!-- + + Written by Claudia Schmeing for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: policygroups.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1>How to Configure Linux FreeS/WAN with Policy Groups</h1> + + +<A NAME="policygroups"></A> + +<H2>What are Policy Groups?</H2> + + +<P><STRONG>Policy Groups</STRONG> are an elegant general mechanism +to configure FreeS/WAN. They are useful for +many FreeS/WAN users.</P> + +<P>In previous FreeS/WAN versions, you needed to configure each IPsec +connection explicitly, on both local and remote hosts. + This could become complex.</P> + +<P>By contrast, Policy Groups allow you to set local IPsec policy +for lists of remote hosts and networks, +simply by listing the hosts and networks which you wish to +have special treatment in one of several Policy Group files. +FreeS/WAN then internally creates the connections +needed to implement each policy.</P> + +<P>In the next section we describe our five Base Policy Groups, which +you can use to configure IPsec in many useful ways. Later, we will +show you how to create an IPsec VPN using one line of configuration for +each remote host or network.</P> + + +<A NAME="builtin_policygroups"></A><H3>Built-In Security Options</H3> + +<P>FreeS/WAN offers these Base Policy Groups:</P> + +<DL> + +<DT>private</DT> + +<DD> +FreeS/WAN only communicates privately with the listed +<A HREF="glossary.html#CIDR">CIDR</A> blocks. +If needed, FreeS/WAN attempts to create a connection opportunistically. +If this fails, FreeS/WAN blocks communication. +Inbound blocking is assumed to be done by the firewall. FreeS/WAN offers +firewall hooks but no modern firewall rules to help with inbound blocking. + +</DD> + +<DT>private-or-clear</DT> +<DD> + +FreeS/WAN prefers private communication with the listed CIDR blocks. +If needed, FreeS/WAN attempts to create a connection opportunistically. +If this fails, FreeS/WAN allows traffic in the clear. + +</DD> + +<DT>clear-or-private</DT> + +<DD> +FreeS/WAN communicates cleartext with the listed CIDR blocks, but +also accepts inbound OE connection requests from them. +Also known as <A HREF="glossary.html#passive.OE">passive OE (pOE)</A>, +this policy may be used to create an +<A HREF="glossary.html#responder">opportunistic responder</A>. +</DD> + +<DT>clear</DT> +<DD> +FreeS/WAN only communicates cleartext with the listed CIDR blocks. +</DD> + +<DT>block</DT> +<DD>FreeS/WAN blocks traffic to and from and the listed CIDR blocks. +Inbound blocking is assumed to be done by the firewall. FreeS/WAN offers +firewall hooks but no modern firewall rules to help with inbound blocking. +<!-- also called "blockdrop".--> + +</DD> + +</DL> + +<A NAME="policy.group.notes"></A><P>Notes:</P> + +<UL> +<LI>Base Policy Groups apply to communication with this host only.</LI> +<LI>The most specific rule (whether policy or pre-configured connection) +applies. +This has several practical applications: +<UL> +<LI>If CIDR blocks overlap, FreeS/WAN chooses +the most specific applicable block.</LI> +<LI>This decision also takes into account any pre-configured connections +you may have.</LI> +<LI>If the most specific connection is a pre-configured connection, +the following procedure applies. If that connection is up, it will be +used. If it is routed, it will be brought up. If it is added, +no action will be taken.</LI> +</UL> +<LI>Base Policy Groups are created using built-in connections. +Details in +<A HREF="manpage.d/ipsec.conf.5.html">man ipsec.conf</A>.</LI> +<LI>All Policy Groups are bidirectional. +<A HREF="src/policy-groups-table.html">This chart</A> shows some technical +details. +FreeS/WAN does not support one-way encryption, since it can give users +a false sense of security.</LI> +</UL> + + +<H2>Using Policy Groups</H2> + +<P>The Base Policy Groups which build IPsec connections rely on Opportunistic +Encryption. To use the following examples, you +must first become OE-capable, as described +in our <A HREF="quickstart.html#quickstart">quickstart guide</A>. + +<A NAME="example1"></A><H3>Example 1: Using a Base Policy Group</H3> + +<P>Simply place CIDR blocks (<A HREF="#dnswarning">names</A>, +IPs or IP ranges) in /etc/ipsec.d/policies/<VAR>[groupname]</VAR>, +and reread the policy group files.</P> + +<P>For example, the <VAR>private-or-clear</VAR> policy tells +FreeS/WAN to prefer encrypted communication to the listed CIDR blocks. +Failing that, it allows talk in the clear.</P> + +<P>To make this your default policy, place +<A HREF="glossary.html#fullnet">fullnet</A> +in the <VAR>private-or-clear</VAR> policy group file:</P> + +<PRE> [root@xy root]# cat /etc/ipsec.d/policies/private-or-clear + # This file defines the set of CIDRs (network/mask-length) to which + # communication should be private, if possible, but in the clear otherwise. + .... + 0.0.0.0/0</PRE> + +<P>and reload your policies with</P> + +<PRE> ipsec auto --rereadgroups</PRE> + +<P>Use <A HREF="quickstart.html#opp.test">this test</A> to verify +opportunistic connections.</P> + + + +<A NAME="example2"></A><H3>Example 2: Defining IPsec Security Policy +with Groups</H3> + +<P>Defining IPsec security policy with Base Policy Groups is like creating +a shopping list: just put CIDR blocks in the appropriate group files. +For example:</P> + + +<PRE> [root@xy root]# cd /etc/ipsec.d/policies + [root@xy policies]# cat private + 192.0.2.96/27 # The finance department + 192.0.2.192/29 # HR + 192.0.2.12 # HR gateway + irc.private.example.com # Private IRC server + + [root@xy policies]# cat private-or-clear + 0.0.0.0/0 # My default policy: try to encrypt. + + [root@xy policies]# cat clear + 192.0.2.18/32 # My POP3 server + 192.0.2.19/32 # My Web proxy + + [root@xy policies]# cat block + spamsource.example.com</PRE> + +<P>To make these settings take effect, type:</P> +<PRE> ipsec auto --rereadgroups</PRE> + + +<P>Notes:</P> +<UL> +<LI>For opportunistic connection attempts to succeed, all participating +FreeS/WAN hosts and gateways must be configured for OE.</LI> +<LI>Examples 3 through 5 show how to implement a detailed <VAR>private</VAR> +policy.</LI> +<LI> +<A NAME="dnswarning"></A> +<FONT COLOR=RED>Warning:</FONT> Using DNS names in policy files and ipsec.conf +can be tricky. If the name does not resolve, the policy will not be +implemented for that name. +It is therefore safer either to use IPs, or to put any critical names +in /etc/hosts. +We plan to implement periodic DNS retry to help with this. +<BR> +Names are resolved at FreeS/WAN startup, or when the policies are reloaded. +Unfortunately, name lookup can hold up the startup process. +If you have fast DNS servers, the problem may be less severe. +</LI> +</UL> + + +<A HREF="example3"></A><H3>Example 3: Creating a Simple IPsec VPN with the +<VAR>private</VAR> Group</H3> + + +<P>You can create an IPsec VPN between several hosts, with +only one line of configuration per host, using the <VAR>private</VAR> +policy group.</P> + +<P>First, use our <A HREF="quickstart.html">quickstart +guide</A> to set up each participating host +with a FreeS/WAN install and OE.</P> + +<P>In one host's <VAR>/etc/ipsec.d/policies/private</VAR>, +list the peers to which you wish to protect traffic. +For example:</P> + +<PRE> [root@xy root]# cd /etc/ipsec.d/policies + [root@xy policies]# cat private + 192.0.2.9 # several hosts at example.com + 192.0.2.11 + 192.0.2.12 + irc.private.example.com +</PRE> + +<P>Copy the <VAR>private</VAR> file to each host. Remove the local host, and +add the initial host.</P> + +<PRE> scp2 /etc/ipsec.d/policies/private root@192.0.2.12:/etc/ipsec.d/policies/private</PRE> + +<P>On each host, reread the policy groups with</P> + +<PRE> ipsec auto --rereadgroups</PRE> + + +<P>That's it! You're configured.</P> + +<P>Test by pinging between two hosts. After a second or two, +traffic should flow, and</P> + +<PRE> ipsec eroute</PRE> + +<P>should yield something like</P> + +<PRE> 192.0.2.11/32 -> 192.0.2.8/32 => tun0x149f@192.0.2.8</PRE> + +<P>where your host IPs are substituted for 192.0.2.11 and 192.0.2.8.</P> + +<P>If traffic does not flow, there may be an error in your OE setup. +Revisit our <A HREF="quickstart.html">quickstart guide</A>.</P> + + +<P>Our next two examples show you how to add subnets to this IPsec VPN.</P> + + +<A NAME="example4"></A><H3>Example 4: New Policy Groups to Protect a +Subnet</H3> + +<P>To protect traffic to a subnet behind your FreeS/WAN gateway, +you'll need additional DNS records, and new policy groups. +To set up the DNS, see our <A HREF="quickstart.html#opp.gate">quickstart +guide</A>. To create five new policy groups for your subnet, +copy these connections to <VAR>/etc/ipsec.conf</VAR>. +Substitute your subnet's IPs for 192.0.2.128/29.</P> + +<PRE> +conn private-net + also=private # inherits settings (eg. auto=start) from built in conn + leftsubnet=192.0.2.128/29 # your subnet's IPs here + +conn private-or-clear-net + also=private-or-clear + leftsubnet=192.0.2.128/29 + +conn clear-or-private-net + also=clear-or-private + leftsubnet=192.0.2.128/29 + +conn clear-net + also=clear + leftsubnet=192.0.2.128/29 + +conn block-net + also=block + leftsubnet=192.0.2.128/29 +</PRE> + +<P>Copy the gateway's files to serve as the initial policy group files for the +new groups:</P> + +<PRE> + cp -p /etc/ipsec.d/policies/private /etc/ipsec.d/policies/private-net + cp -p /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private-or-clear-net + cp -p /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/clear-or-private-net + cp -p /etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-net + cp -p /etc/ipsec.d/policies/block /etc/ipsec.d/policies/block +</PRE> + +<P><STRONG>Tip: Since a missing policy group file is equivalent to a file with +no entries, you need only create files for the connections +you'll use.</STRONG></P> + +<P>To test one of your new groups, place the fullnet 0.0.0.0/0 in +<VAR>private-or-clear-net</VAR>. +Perform the subnet test in +<A HREF="quickstart.html#opp.test">our quickstart guide</A>. You should +see a connection, and</P> + +<PRE> ipsec eroute</PRE> + +<P>should include an entry which mentions the subnet node's IP and the +OE test site IP, like this:</P> + +<PRE> 192.0.2.131/32 -> 192.139.46.77/32 => tun0x149f@192.0.2.11</PRE> + + +<A HREF="example5"></A><H3>Example 5: Adding a Subnet to the VPN</H3> + +<P>Suppose you wish to secure traffic to a subnet 192.0.2.192/29 +behind a FreeS/WAN box 192.0.2.12.</P> + +<P>First, add DNS entries to configure 192.0.2.12 as an opportunistic +gateway for that subnet. Instructions are in + our <A HREF="quickstart.html#opp.gate">quickstart guide</A>. +Next, create a <VAR>private-net</VAR> group on 192.0.2.12 as described in +<A HREF="#example4">Example 4</A>. +</P> + +<P>On each other host, add the subnet 192.0.2.192/29 to <VAR>private</VAR>, +yielding for example</P> + +<PRE> [root@xy root]# cd /etc/ipsec.d/policies + [root@xy policies]# cat private + 192.0.2.9 # several hosts at example.com + 192.0.2.11 + 192.0.2.12 # HR department gateway + 192.0.2.192/29 # HR subnet + irc.private.example.com +</PRE> + + +<P>and reread policy groups with </P> + +<PRE> ipsec auto --rereadgroups</PRE> + +<P>That's all the configuration you need.</P> + +<P>Test your VPN by pinging from a machine on 192.0.2.192/29 to any other host: +</P> + +<PRE> [root@192.0.2.194]# ping 192.0.2.11</PRE> + + +<P>After a second or two, traffic should flow, and</P> + +<PRE> ipsec eroute</PRE> + +<P>should yield something like</P> + +<PRE> 192.0.2.11/32 -> 192.0.2.194/32 => tun0x149f@192.0.2.12 +</PRE> + +<P>Key:</P> +<TABLE> +<TR><TD>1.</TD> + <TD>192.0.2.11/32</TD> + <TD>Local start point of the protected traffic. + </TD></TR> +<TR><TD>2.</TD> + <TD>192.0.2.194/32</TD> + <TD>Remote end point of the protected traffic. + </TD></TR> +<TR><TD>3.</TD> + <TD>192.0.2.12</TD> + <TD>Remote FreeS/WAN node (gateway or host). + May be the same as (2). + </TD></TR> +<TR><TD>4.</TD> + <TD>[not shown]</TD> + <TD>Local FreeS/WAN node (gateway or host), + where you've produced the output. + May be the same as (1). + </TD></TR> +</TABLE> + +<P>For additional assurance, you can verify with a packet sniffer +that the traffic is being encrypted.</P> + + +<P>Note</P> +<UL> +<LI>Because strangers may also connect via OE, +this type of VPN may require a stricter firewalling policy than a +conventional VPN.</LI></UL> + + + +<H2>Appendix</H2> + +<A NAME="hiddenconn"></A><H3>Our Hidden Connections</H3> + + +<P>Our Base Policy Groups are created using hidden connections. +These are spelled out in +<A HREF="manpage.d/ipsec.conf.5.html">man ipsec.conf</A> + and defined in <VAR>/usr/local/lib/ipsec/_confread</VAR>. +</P> + + +<A NAME="custom_policygroups"></A><H3>Custom Policy Groups</H3> + +<P>A policy group is built using a special connection description +in <VAR>ipsec.conf</VAR>, which:</P> + +<UL> +<LI>is <STRONG>generic</STRONG>. It uses +<VAR>right=[%group|%opportunisticgroup]</VAR> rather than specific IPs. +The connection is cloned for every name or IP range listed in its Policy Group +file.</LI> +<LI>often has a <STRONG>failure rule</STRONG>. This rule, written +<VAR>failureshunt=[passthrough|drop|reject|none]</VAR>, tells FreeS/WAN +what to do with packets for these CIDRs if it fails to establish the connection. +Default is <VAR>none</VAR>. +</LI> +</UL> + +<P>To create a new group:</P> +<OL> +<LI>Create its connection definition in <VAR>ipsec.conf</VAR>.</LI> +<LI>Create a Policy Group file in <VAR>/etc/ipsec.d/policies</VAR> +with the same name as your connection. +</LI> +<LI>Put a CIDR block in that file.</LI> +<LI>Reread groups with <VAR>ipsec auto --rereadgroups</VAR>.</LI> +<LI>Test: <VAR>ping</VAR> to activate any OE connection, and view +results with <VAR>ipsec eroute</VAR>.</LI> +</OL> + +<A NAME="disable_oe"></A> +<A NAME="disable_policygroups"></A><H3>Disabling Opportunistic Encryption</H3> + +<P>To disable OE (eg. policy groups and packetdefault), cut and paste the following lines +to <VAR>/etc/ipsec.conf</VAR>:</P> + +<PRE>conn block + auto=ignore + +conn private + auto=ignore + +conn private-or-clear + auto=ignore + +conn clear-or-private + auto=ignore + +conn clear + auto=ignore + +conn packetdefault + auto=ignore</PRE> + +<P>Restart FreeS/WAN so that the changes take effect:</P> + +<PRE> ipsec setup restart</PRE> + +</body> +</html> + + diff --git a/doc/src/politics.html b/doc/src/politics.html new file mode 100644 index 000000000..9e87d4f05 --- /dev/null +++ b/doc/src/politics.html @@ -0,0 +1,1466 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>History and politics of cryptography</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, cryptography, history, politics"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: politics.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="politics">History and politics of cryptography</a></h1> + +<p>Cryptography has a long and interesting history, and has been the subject +of considerable political controversy.</p> + +<h2><a name="intro.politics">Introduction</a></h2> + +<h3>History</h3> + +<p>The classic book on the history of cryptography is David Kahn's <a +href="biblio.html#Kahn">The Codebreakers</a>. It traces codes and +codebreaking from ancient Egypt to the 20th century.</p> + +<p>Diffie and Landau <a href="biblio.html#diffie">Privacy on the Line: The +Politics of Wiretapping and Encryption</a> covers the history from the First +World War to the 1990s, with an emphasis on the US.</p> + +<h4>World War II</h4> + +<p>During the Second World War, the British "Ultra" project achieved one of +the greatest intelligence triumphs in the history of warfare, breaking many +Axis codes. One major target was the Enigma cipher machine, a German device +whose users were convinced it was unbreakable. The American "Magic" project +had some similar triumphs against Japanese codes.</p> + +<p>There are many books on this period. See our bibliography for several. Two +I particularly like are:</p> +<ul> + <li>Andrew Hodges has done a superb <a + href="http://www.turing.org.uk/book/">biography</a> of Alan Turing, a key + player among the Ultra codebreakers. Turing was also an important + computer pioneer. The terms <a + href="http://www.abelard.org/turpap/turpap.htm">Turing test</a> and <a + href="http://plato.stanford.edu/entries/turing-machine/">Turing + machine</a> are named for him, as is the <a + href="http://www.acm.org">ACM</a>'s highest technical <a + href="http://www.acm.org/awards/taward.html">award</a>.</li> + <li>Neal Stephenson's <a href="biblio.html#neal">Cryptonomicon</a> is a + novel with cryptography central to the plot. Parts of it take place + during WW II, other parts today.</li> +</ul> + +<p>Bletchley Park, where much of the Ultra work was done, now has a museum +and a <a href="http://www.bletchleypark.org.uk/">web site</a>.</p> + +<p>The Ultra work introduced three major innovations.</p> +<ul> + <li>The first break of Enigma was achieved by Polish Intelligence in 1931. + Until then most code-breakers had been linguists, but a different + approach was needed to break machine ciphers. Polish Intelligence + recruited bright young mathematicians to crack the "unbreakable" Enigma. + When war came in 1939, the Poles told their allies about this, putting + Britain on the road to Ultra. The British also adopted a mathematical + approach.</li> + <li>Machines were extensively used in the attacks. First the Polish "Bombe" + for attacking Enigma, then British versions of it, then machines such as + Collosus for attacking other codes. By the end of the war, some of these + machines were beginning to closely resemble digital computers. After the + war, a team at Manchester University, several old Ultra hands included, + built one of the world's first actual general-purpose digital + computers.</li> + <li>Ultra made codebreaking a large-scale enterprise, producing + intelligence on an industrial scale. This was not a "black chamber", not + a hidden room in some obscure government building with a small crew of + code-breakers. The whole operation -- from wholesale interception of + enemy communications by stations around the world, through large-scale + code-breaking and analysis of the decrypted material (with an enormous + set of files for cross-referencing), to delivery of intelligence to field + commanders -- was huge, and very carefully managed.</li> +</ul> + +<p>So by the end of the war, Allied code-breakers were expert at large-scale +mechanised code-breaking. The payoffs were enormous.</p> + +<h4><a name="postwar">Postwar and Cold War</a></h4> + +<p>The wartime innovations were enthusiastically adopted by post-war and Cold +War signals intelligence agencies. Presumably many nations now have some +agency capable of sophisticated attacks on communications security, and quite +a few engage in such activity on a large scale.</p> + +<p>America's <a href="glossary.html#NSA">NSA</a>, for example, is said to be +both the world's largest employer of mathematicians and the world's largest +purchaser of computer equipment. Such claims may be somewhat exaggerated, but +beyond doubt the NSA -- and similar agencies in other countries -- have some +excellent mathematicians, lots of powerful computers, sophisticated software, +and the organisation and funding to apply them on a large scale. Details of +the NSA budget are secret, but there are some published <a +href="http://www.fas.org/irp/nsa/nsabudget.html">estimates</a>.</p> + +<p>Changes in the world's communications systems since WW II have provided +these agencies with new targets. Cracking the codes used on an enemy's +military or diplomatic communications has been common practice for centuries. +Extensive use of radio in war made large-scale attacks such as Ultra +possible. Modern communications make it possible to go far beyond that. +Consider listening in on cell phones, or intercepting electronic mail, or +tapping into the huge volumes of data on new media such as fiber optics or +satellite links. None of these targets existed in 1950. All of them can be +attacked today, and almost certainly are being attacked.</p> + +<p>The Ultra story was not made public until the 1970s. Much of the recent +history of codes and code-breaking has not been made public, and some of it +may never be. Two important books are:</p> +<ul> + <li>Bamford's <a href="biblio.html#puzzle">The Puzzle Palace</a>, a history + of the NSA</li> + <li>Hager's <a href="http://www.fas.org/irp/eprint/sp/index.html">Secret + Power</a>, about the <a + href="http://sg.yahoo.com/government/intelligence/echelon_network/">Echelon</a> + system -- the US, UK, Canada, Australia and New Zealand co-operating to + monitor much of the world's communications.</li> +</ul> + +<p>Note that these books cover only part of what is actually going on, and +then only the activities of nations open and democratic enough that (some of) +what they are doing can be discovered. A full picture, including:</p> +<ul> + <li>actions of the English-speaking democracies not covered in those + books</li> + <li>actions of other more-or-less sane governments</li> + <li>the activities of various more-or-less insane governments</li> + <li>possibilities for unauthorized action by government employees</li> + <li>possible actions by large non-government organisations: corporations, + criminals, or conspiracies</li> +</ul> + +<p>might be really frightening.</p> + +<h4><a name="recent">Recent history -- the crypto wars</a></h4> + +<p>Until quite recently, cryptography was primarily a concern of governments, +especially of the military, of spies, and of diplomats. Much of it was +extremely secret.</p> + +<p>In recent years, that has changed a great deal. With computers and +networking becoming ubiquitous, cryptography is now important to almost +everyone. Among the developments since the 1970s:</p> +<ul> + <li>The US gov't established the Data Encryption Standard, <a + href="glossary.html#DES">DES</a>, a <a href="glossary.html#block">block + cipher</a> for cryptographic protection of unclassfied documents.</li> + <li>DES also became widely used in industry, especially regulated + industries such as banking.</li> + <li>Other nations produced their own standards, such as <a + href="glossary.html#GOST">GOST</a> in the Soviet Union.</li> + <li><a href="glossary.html#public">Public key</a> cryptography was invented + by Diffie and Hellman.</li> + <li>Academic conferences such as <a + href="http://www-cse.ucsd.edu/users/mihir/crypto2k.html">Crypto</a> and + <a + href="http://www.esat.kuleuven.ac.be/cosic/eurocrypt2000/">Eurocrypt</a> + began.</li> + <li>Several companies began offerring cryptographic products: <a + href="glossary.html#RSAco">RSA</a>, <a href="glossary.html#PGPI">PGP</a>, + the many vendors with <a href="glossary.html#PKI">PKI</a> products, + ...</li> + <li>Cryptography appeared in other products: operating systems, word + processors, ...</li> + <li>Network protocols based on crypto were developed: <a + href="glossary.html#SSH">SSH</a>, <a href="glossary.html#SSL">SSL</a>, <a + href="glossary.html#IPsec">IPsec</a>, ...</li> + <li>Crytography came into widespread use to secure bank cards, terminals, + ...</li> + <li>The US government replaced <a href="glossary.html#DES">DES</a> with the + much stronger Advanced Encryption Standard, <a + href="glossary.html#AES">AES</a></li> +</ul> + +<p>This has led to a complex ongoing battle between various mainly government +groups wanting to control the spread of crypto and various others, notably +the computer industry and the <a +href="http://online.offshore.com.ai/security/">cypherpunk</a> crypto +advocates, wanting to encourage widespread use.</p> + +<p>Steven Levy has written a fine history of much of this, called <a +href="biblio.html#crypto">Crypto: How the Code rebels Beat the Government -- +Saving Privacy in the Digital Age</a>.</p> + +<p>The FreeS/WAN project is to a large extent an outgrowth of cypherpunk +ideas. Our reasons for doing the project can be seen in these quotes from the +<a +href="http://www.eff.org/pub/Privacy/Crypto_misc/cypherpunk.manifesto">Cypherpunk +Manifesto</a>:</p> + +<blockquote> + Privacy is necessary for an open society in the electronic age. ... + + <p>We cannot expect governments, corporations, or other large, faceless + organizations to grant us privacy out of their beneficence. It is to their + advantage to speak of us, and we should expect that they will speak. + ...</p> + + <p>We must defend our own privacy if we expect to have any. ...</p> + + <p>Cypherpunks write code. We know that someone has to write software to + defend privacy, and since we can't get privacy unless we all do, we're + going to write it. We publish our code so that our fellow Cypherpunks may + practice and play with it. Our code is free for all to use, worldwide. We + don't much care if you don't approve of the software we write. We know + that software can't be destroyed and that a widely dispersed system can't + be shut down.</p> + + <p>Cypherpunks deplore regulations on cryptography, for encryption is + fundamentally a private act. ...</p> + + <p>For privacy to be widespread it must be part of a social contract. + People must come and together deploy these systems for the common good. + ...</p> +</blockquote> + +<p>To quote project leader John Gilmore:</p> + +<blockquote> + We are literally in a race between our ability to build and deploy + technology, and their ability to build and deploy laws and treaties. + Neither side is likely to back down or wise up until it has definitively + lost the race.</blockquote> + +<p>If FreeS/WAN reaches its goal of making <a +href="intro.html#opp.intro">opportunistic encryption</a> widespread so that +secure communication can become the default for a large part of the net, we +will have struck a major blow.</p> + +<h3><a name="intro.poli">Politics</a></h3> + +<p>The political problem is that nearly all governments want to monitor their +enemies' communications, and some want to monitor their citizens. They may be +very interested in protecting some of their own communications, and often +some types of business communication, but not in having everyone able to +communicate securely. They therefore attempt to restrict availability of +strong cryptography as much as possible.</p> + +<p>Things various governments have tried or are trying include:</p> +<ul> + <li>Echelon, a monitor-the-world project of the US, UK, NZ, Australian and + Canadian <a href="glossary.html#SIGINT">signals intelligence</a> + agencies. See this <a + href="http://sg.yahoo.com/government/intelligence/echelon_network/">collection</a> + of links and this <a + href="http://www.zdnet.com/zdnn/stories/news/0,4586,2640682,00.html">story</a> + on the French Parliament's reaction.</li> + <li>Others governments may well have their own Echelon-like projects. To + quote the Dutch Minister of Defense, as reported in a German <a + href="http://www.heise.de/tp/english/inhalt/te/4729/1.html">magazine</a>: + + <blockquote> + The government believes not only the governments associated with + Echelon are able to intercept communication systems, but that it is an + activity of the investigative authorities and intelligence services of + many countries with governments of different political + signature.</blockquote> + Even if they have nothing on the scale of Echelon, most intelligence + agencies and police forces certainly have some interception + capability.</li> + <li><a href="glossary.html#NSA">NSA</a> tapping of submarine communication + cables, described in <a + href="http://www.zdnet.com/zdnn/stories/news/0,4586,2764372,00.html">this + article</a></li> + <li>A proposal for international co-operation on <a + href="http://www.heise.de/tp/english/special/enfo/4306/1.html">Internet + surveillance</a>.</li> + <li>Alleged <a href="http://cryptome.org/nsa-sabotage.htm">sabotage</a> of + security products by the <a href="glossary.html#NSA">NSA</a> (the US + signals intelligence agency).</li> + <li>The German armed forces and some government departments will stop using + American software for fear of NSA "back doors", according to this <a + href="http://www.theregister.co.uk/content/4/17679.html">news + story</a>.</li> + <li>The British Regulation of Investigatory Powers bill. See this <a + href="http://www.fipr.org/rip/index.html">web page.</a> and perhaps this + <a + href="http://ars.userfriendly.org/cartoons/?id=20000806&mode=classic">cartoon</a>.</li> + <li>A Russian <a + href="http://www.eff.org/pub/Privacy/Foreign_and_local/Russia/russian_crypto_ban_english.edict">ban</a> + on cryptography</li> + <li>Chinese <a + href="http://www.eff.org/pub/Misc/Publications/Declan_McCullagh/www/global/china">controls</a> + on net use.</li> + <li>The FBI's carnivore system for covert searches of email. See this <a + href="http://www.zdnet.com/zdnn/stories/news/0,4586,2601502,00.html">news + coverage</a> and this <a + href="http://www.crypto.com/papers/carnivore-risks.html">risk + assessment</a>. The government had an external review of some aspects of + this system done. See this <a + href="http://www.crypto.com/papers/carnivore_report_comments.html">analysis</a> + of that review. Possible defenses against Carnivore include: + <ul> + <li><a href="glossary.html#PGP">PGP</a> for end-to-end mail + encryption</li> + <li><a href="http://www.home.aone.net.au/qualcomm/">secure sendmail</a> + for server-to-server encryption</li> + <li>IPsec encryption on the underlying IP network</li> + </ul> + </li> + <li>export laws restricting strong cryptography as a munition. See <a + href="#exlaw">discussion</a> below.</li> + <li>various attempts to convince people that fundamentally flawed + cryptography, such as encryption with a <a href="#escrow">back door</a> + for government access to data or with <a href="#shortkeys">inadequate key + lengths</a>, was adequate for their needs.</li> +</ul> + +<p>Of course governments are by no means the only threat to privacy and +security on the net. Other threats include:</p> +<ul> + <li>industrial espionage, as for example in this <a + href="http://www.zdnet.com/zdnn/stories/news/0,4586,2626931,00.html">news + story</a></li> + <li>attacks by organised criminals, as in this <a + href="http://www.sans.org/newlook/alerts/NTE-bank.htm">large-scale + attack</a></li> + <li>collection of personal data by various companies. + <ul> + <li>for example, consider the various corporate winners of Privacy + International's <a + href="http://www.privacyinternational.org/bigbrother/">Big Brother + Awards</a>.</li> + <li><a href="http://www.zeroknowledge.com">Zero Knowledge</a> sell + tools to defend against this</li> + </ul> + </li> + <li>individuals may also be a threat in a variety of ways and for a variety + of reasons</li> + <li>in particular, an individual with access to government or industry data + collections could do considerable damage using that data in unauthorized + ways.</li> +</ul> + +<p>One <a +href="http://www.zdnet.com/zdnn/stories/news/0,4586,2640674,00.html">study</a> +enumerates threats and possible responses for small and medium businesses. +VPNs are a key part of the suggested strategy.</p> + +<p>We consider privacy a human right. See the UN's <a href="http://www.un.org/Overview/rights.html">Universal +Declaration of Human Rights</a>, article twelve:</p> + +<blockquote> + No one shall be subjected to arbitrary interference with his privacy, + family, home or correspondence, nor to attacks upon his honor and + reputation. Everyone has the right to the protection of the law against + such interference or attacks.</blockquote> + +<p>Our objective is to help make privacy possible on the Internet using +cryptography strong enough not even those well-funded government agencies are +likely to break it. If we can do that, the chances of anyone else breaking it +are negliible.</p> + +<h3>Links</h3> + +<p>Many groups are working in different ways to defend privacy on the net and +elsewhere. Please consider contributing to one or more of these groups:</p> +<ul> + <li>the EFF's <a href="http://www.eff.org/crypto/">Privacy Now!</a> + campaign</li> + <li>the <a href="http://www.gilc.org">Global Internet Liberty + Campaign</a></li> + <li><a href="http://www.cpsr.org/program/privacy/privacy.html">Computer + Professionals for Social Responsibility</a></li> +</ul> + +<p>For more on these issues see:</p> +<ul> + <li>Steven Levy (Newsweek's chief technology writer and author of the + classic "Hackers") new book <a href="biblio.html#crypto">Crypto: How the + Code Rebels Beat the Government--Saving Privacy in the Digital + Age</a></li> + <li>Simson Garfinkel (Boston Globe columnist and author of books on <a + href="biblio.html#PGP">PGP</a> and <a href="biblio.html#practical">Unix + Security</a>) book <a href="biblio.html#Garfinkel">Database Nation: the + death of privacy in the 21st century</a></li> +</ul> + +<p>There are several collections of <a href="web.html#quotes">crypto +quotes</a> on the net.</p> + +<p>See also the <a href="biblio.html">bibliography</a> and our list of <a +href="web.html#policy">web references</a> on cryptography law and policy.</p> + +<h3>Outline of this section</h3> + +<p>The remainder of this section includes two pieces of writing by our +project leader</p> +<ul> + <li>his <a href="#gilmore">rationale</a> for starting this</li> + <li>another <a href="#policestate">discussion</a> of project goals</li> +</ul> + +<p>and discussions of:</p> +<ul> + <li><a href="#desnotsecure">why we do not use DES</a></li> + <li><a href="#exlaw">cryptography export laws</a></li> + <li>why <a href="#escrow">government access to keys</a> is not a good + idea</li> + <li>the myth that <a href="#shortkeys">short keys</a> are adequate for some + security requirements</li> +</ul> + +<p>and a section on <a href="#press">press coverage of FreeS/WAN</a>.</p> + +<h2><a name="leader">From our project leader</a></h2> + +<p>FreeS/WAN project founder John Gilmore wrote a web page about why we are +doing this. The version below is slightly edited, to fit this format and to +update some links. For a version without these edits, see his <a +href="http://www.toad.com/gnu/">home page</a>.</p> + +<center> +<h3><a name="gilmore">Swan: Securing the Internet against Wiretapping</a></h3> +</center> + +<p>My project for 1996 was to <b>secure 5% of the Internet traffic against +passive wiretapping</b>. It didn't happen in 1996, so I'm still working on it +in 1997, 1998, and 1999! If we get 5% in 1999 or 2000, we can secure 20% the +next year, against both active and passive attacks; and 80% the following +year. Soon the whole Internet will be private and secure. The project is +called S/WAN or S/Wan or Swan for Secure Wide Area Network; since it's free +software, we call it FreeSwan to distinguish it from various commercial +implementations. <a href="http://www.rsa.com/rsa/SWAN/">RSA</a> came up with +the term "S/WAN". Our main web site is at <a +href="http://www.freeswan.org/">http://www.freeswan.org/</a>. Want to +help?</p> + +<p>The idea is to deploy PC-based boxes that will sit between your local area +network and the Internet (near your firewall or router) which +opportunistically encrypt your Internet packets. Whenever you talk to a +machine (like a Web site) that doesn't support encryption, your traffic goes +out "in the clear" as usual. Whenever you connect to a machine that does +support this kind of encryption, this box automatically encrypts all your +packets, and decrypts the ones that come in. In effect, each packet gets put +into an "envelope" on one side of the net, and removed from the envelope when +it reaches its destination. This works for all kinds of Internet traffic, +including Web access, Telnet, FTP, email, IRC, Usenet, etc.</p> + +<p>The encryption boxes are standard PC's that use freely available Linux +software that you can download over the Internet or install from a cheap +CDROM.</p> + +<p>This wasn't just my idea; lots of people have been working on it for +years. The encryption protocols for these boxes are called <a +href="glossary.html#IPsec">IPSEC (IP Security)</a>. They have been developed +by the <a +href="http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html">IP +Security Working Group</a> of the <a href="http://www.ietf.org/">Internet +Engineering Task Force</a>, and will be a standard part of the next major +version of the Internet protocols (<a +href="http://playground.sun.com/pub/ipng/html/ipng-main.html">IPv6</a>). For +today's (IP version 4) Internet, they are an option.</p> + +<p>The <a href="http://www.iab.org/iab">Internet Architecture Board</a> and +<a href="http://www.ietf.org/">Internet Engineering Steering Group</a> have +taken a <a href="iab-iesg.stmt">strong stand</a> that the Internet should use +powerful encryption to provide security and privacy. I think these protocols +are the best chance to do that, because they can be deployed very easily, +without changing your hardware or software or retraining your users. They +offer the best security we know how to build, using the Triple-DES, RSA, and +Diffie-Hellman algorithms.</p> + +<p>This "opportunistic encryption box" offers the "fax effect". As each +person installs one for their own use, it becomes more valuable for their +neighbors to install one too, because there's one more person to use it with. +The software automatically notices each newly installed box, and doesn't +require a network administrator to reconfigure it. Instead of "virtual +private networks" we have a "REAL private network"; we add privacy to the +real network instead of layering a manually-maintained virtual network on top +of an insecure Internet.</p> + +<h4>Deployment of IPSEC</h4> + +<p>The US government would like to control the deployment of IP Security with +its <a href="#exlaw">crypto export laws</a>. This isn't a problem for my +effort, because the cryptographic work is happening outside the United +States. A foreign philanthropist, and others, have donated the resources +required to add these protocols to the Linux operating system. <a +href="http://www.linux.org/">Linux</a> is a complete, freely available +operating system for IBM PC's and several kinds of workstation, which is +compatible with Unix. It was written by Linus Torvalds, and is still +maintained by a talented team of expert programmers working all over the +world and coordinating over the Internet. Linux is distributed under the <a +href="glossary.html#GPL">GNU Public License</a>, which gives everyone the +right to copy it, improve it, give it to their friends, sell it commercially, +or do just about anything else with it, without paying anyone for the +privilege.</p> + +<p>Organizations that want to secure their network will be able to put two +Ethernet cards into an IBM PC, install Linux on it from a $30 CDROM or by +downloading it over the net, and plug it in between their Ethernet and their +Internet link or firewall. That's all they'll have to do to encrypt their +Internet traffic everywhere outside their own local area network.</p> + +<p>Travelers will be able to run Linux on their laptops, to secure their +connection back to their home network (and to everywhere else that they +connect to, such as customer sites). Anyone who runs Linux on a standalone PC +will also be able to secure their network connections, without changing their +application software or how they operate their computer from day to day.</p> + +<p>There will also be numerous commercially available firewalls that use this +technology. <a href="http://www.rsa.com/">RSA Data Security</a> is +coordinating the <a href="http://www.rsa.com/rsa/SWAN">S/Wan (Secure Wide +Area Network)</a> project among more than a dozen vendors who use these +protocols. There's a <a +href="http://www.rsa.com/rsa/SWAN/swan_test.htm">compatability chart</a> that +shows which vendors have tested their boxes against which other vendors to +guarantee interoperatility.</p> + +<p>Eventually it will also move into the operating systems and networking +protocol stacks of major vendors. This will probably take longer, because +those vendors will have to figure out what they want to do about the export +controls.</p> + +<h4>Current status</h4> + +<p>My initial goal of securing 5% of the net by Christmas '96 was not met. It +was an ambitious goal, and inspired me and others to work hard, but was +ultimately too ambitious. The protocols were in an early stage of +development, and needed a lot more protocol design before they could be +implemented. As of April 1999, we have released version 1.0 of the software +(<a +href="ftp://ftp.xs4all.nl/freeswan/freeswan-1.0.tar.gz">freeswan-1.0.tar.gz</a>), +which is suitable for setting up Virtual Private Networks using shared +secrets for authentication. It does not yet do opportunistic encryption, or +use DNSSEC for authentication; those features are coming in a future +release.</p> +<dl> + <dt>Protocols</dt> + <dd>The low-level encrypted packet formats are defined. The system for + publishing keys and providing secure domain name service is defined. + The IP Security working group has settled on an NSA-sponsored protocol + for key agreement (called ISAKMP/Oakley), but it is still being worked + on, as the protocol and its documentation is too complex and + incomplete. There are prototype implementations of ISAKMP. The + protocol is not yet defined to enable opportunistic encryption or the + use of DNSSEC keys.</dd> + <dt>Linux Implementation</dt> + <dd>The Linux implementation has reached its first major release and is + ready for production use in manually-configured networks, using Linux + kernel version 2.0.36.</dd> + <dt>Domain Name System Security</dt> + <dd>There is now a release of BIND 8.2 that includes most DNS Security + features. + <p>The first prototype implementation of Domain Name System Security + was funded by <a href="glossary.html#DARPA">DARPA</a> as part of their + <a href="http://www.darpa.mil/ito/research/is/index.html">Information + Survivability program</a>. <a href="http://www.tis.com">Trusted + Information Systems</a> wrote a modified version of <a + href="http://www.isc.org/bind.html">BIND</a>, the widely-used Berkeley + implementation of the Domain Name System.</p> + <p>TIS, ISC, and I merged the prototype into the standard version of + BIND. The first production version that supports KEY and SIG records is + <b>bind-4.9.5</b>. This or any later version of BIND will do for + publishing keys. It is available from the <a + href="http://www.isc.org/bind.html">Internet Software Consortium</a>. + This version of BIND is not export-controlled since it does not contain + any cryptography. Later releases starting with BIND 8.2 include + cryptography for authenticating DNS records, which is also exportable. + Better documentation is needed.</p> + </dd> +</dl> + +<h4>Why?</h4> + +<p>Because I can. I have made enough money from several successful startup +companies, that for a while I don't have to work to support myself. I spend +my energies and money creating the kind of world that I'd like to live in and +that I'd like my (future) kids to live in. Keeping and improving on the civil +rights we have in the United States, as we move more of our lives into +cyberspace, is a particular goal of mine.</p> + +<h4>What You Can Do</h4> +<dl> + <dt>Install the latest BIND at your site.</dt> + <dd>You won't be able to publish any keys for your domain, until you have + upgraded your copy of BIND. The thing you really need from it is the + new version of <i>named</i>, the Name Daemon, which knows about the new + KEY and SIG record types. So, download it from the <a + href="http://www.isc.org/bind.html">Internet Software Consortium </a> + and install it on your name server machine (or get your system + administrator, or Internet Service Provider, to install it). Both your + primary DNS site and all of your secondary DNS sites will need the new + release before you will be able to publish your keys. You can tell + which sites this is by running the Unix command "dig MYDOMAIN ns" and + seeing which sites are mentioned in your NS (name server) records.</dd> + <dt>Set up a Linux system and run a 2.0.x kernel on it</dt> + <dd>Get a machine running Linux (say the 5.2 release from <a + href="http://www.redhat.com">Red Hat</a>). Give the machine two + Ethernet cards.</dd> + <dt>Install the Linux IPSEC (Freeswan) software</dt> + <dd>If you're an experienced sysadmin or Linux hacker, install the + freeswan-1.0 release, or any later release or snapshot. These releases + do NOT provide automated "opportunistic" operation; they must be + manually configured for each site you wish to encrypt with.</dd> + <dt>Get on the linux-ipsec mailing list</dt> + <dd>The discussion forum for people working on the project, and testing + the code and documentation, is: linux-ipsec@clinet.fi. To join this + mailing list, send email to <a + href="mailto:linux-ipsec-REQUEST@clinet.fi">linux-ipsec-REQUEST@clinet.fi</a> + containing a line of text that says "subscribe linux-ipsec". (You can + later get off the mailing list the same way -- just send "unsubscribe + linux-ipsec").</dd> + + <p></p> + <dt>Check back at this web page every once in a while</dt> + <dd>I update this page periodically, and there may be new information in + it that you haven't seen. My intent is to send email to the mailing + list when I update the page in any significant way, so subscribing to + the list is an alternative.</dd> +</dl> + +<p>Would you like to help? I can use people who are willing to write +documentation, install early releases for testing, write cryptographic code +outside the United States, sell pre-packaged software or systems including +this technology, and teach classes for network administrators who want to +install this technology. To offer to help, send me email at gnu@toad.com. +Tell me what country you live in and what your citizenship is (it matters due +to the export control laws; personally I don't care). Include a copy of your +resume and the URL of your home page. Describe what you'd like to do for the +project, and what you're uniquely qualified for. Mention what other +volunteer projects you've been involved in (and how they worked out). Helping +out will require that you be able to commit to doing particular things, meet +your commitments, and be responsive by email. Volunteer projects just don't +work without those things.</p> + +<h4>Related projects</h4> +<dl> + <dt>IPSEC for NetBSD</dt> + <dd>This prototype implementation of the IP Security protocols is for + another free operating system. <a + href="ftp://ftp.funet.fi/pub/unix/security/net/ip/BSDipsec.tar.gz">Download + BSDipsec.tar.gz</a>.</dd> + <dt>IPSEC for <a href="http://www.openbsd.org">OpenBSD</a></dt> + <dd>This prototype implementation of the IP Security protocols is for yet + another free operating system. It is directly integrated into the OS + release, since the OS is maintained in Canada, which has freedom of + speech in software.</dd> +</dl> + +<h3><a name="policestate">Stopping wholesale monitoring</a></h3> + +<p>From a message project leader John Gilmore posted to the mailing list:</p> +<pre>John Denker wrote: + +> Indeed there are several ways in which the documentation overstates the +> scope of what this project does -- starting with the name +> FreeS/WAN. There's a big difference between having an encrypted IP tunnel +> versus having a Secure Wide-Area Network. This software does a fine job of +> the former, which is necessary but not sufficient for the latter. + +The goal of the project is to make it very hard to tap your wide area +communications. The current system provides very good protection +against passive attacks (wiretapping and those big antenna farms). +Active attacks, which involve the intruder sending packets to your +system (like packets that break into sendmail and give them a root +shell :-) are much harder to guard against. Active attacks that +involve sending people (breaking into your house and replacing parts +of your computer with ones that transmit what you're doing) are also +much harder to guard against. Though we are putting effort into +protecting against active attacks, it's a much bigger job than merely +providing strong encryption. It involves general computer security, +and general physical security, which are two very expensive problems +for even a site to solve, let alone to build into a whole society. + +The societal benefit of building an infrastructure that protects +well against passive attacks is that it makes it much harder to do +undetected bulk monitoring of the population. It's a defense against +police-states, not against policemen. + +Policemen can put in the effort required to actively attack sites that +they have strong suspicions about. But police states won't be able to +build systems that automatically monitor everyone's communications. +Either they will be able to monitor only a small subset of the +populace (by targeting those who screwed up their passive security), +or their monitoring activities will be detectable by those monitored +(active attacks leave packet traces or footprints), which can then be +addressed through the press and through political means if they become +too widespread. + +FreeS/WAN does not protect very well against traffic analysis, which +is a kind of widespread police-state style monitoring that still +reveals significant information (who's talking to who) without +revealing the contents of what was said. Defenses against traffic +analysis are an open research problem. Zero Knowledge Systems is +actively deploying a system designed to thwart it, designed by Ian +Goldberg. The jury is out on whether it actually works; a lot more +experience with it will be needed.</pre> + +<p>Notes on things mentioned in that message:</p> +<ul> + <li>Denker is a co-author of a <a href="intro.html#applied">paper</a> on a + large FreeS/WAN application.</li> + <li>Information on Zero Knowledge is on their <a + href="http://www.zks.net/">web site</a>. Their Freedom product, designed + to provide untracable pseudonyms for use on the net, is no longer + marketed.</li> + <li>Another section of our documentation discusses ways to <a + href="ipsec.html#traffic.resist">resist traffic analysis</a>.</li> +</ul> + +<h2><a name="weak">Government promotion of weak crypto</a></h2> + +<p>Various groups, especially governments and especially the US government, +have a long history of advocating various forms of bogus security.</p> + +<p>We regard bogus security as extremely dangerous. If users are deceived +into relying on bogus security, then they may be exposed to large risks. They +would be better off having no security and knowing it. At least then they +would be careful about what they said.</p> + +<p><strong>Avoiding bogus security is a key design criterion for everything +we do in FreeS/WAN</strong>. The most conspicuous example is our refusal to +support <a href="#desnotsecure">single DES</a>. Other IPsec "features" which +we do not implement are discussed in our <a +href="compat.html#dropped">compatibility</a> document.</p> + +<h3><a name="escrow">Escrowed encryption</a></h3> + +<p>Various governments have made persistent attempts to encourage or mandate +"escrowed encrytion", also called "key recovery", or GAK for "government +access to keys". The idea is that cryptographic keys be held by some third +party and turned over to law enforcement or security agencies under some +conditions.</p> +<pre> Mary had a little key - she kept it in escrow, + and every thing that Mary said, + the feds were sure to know.</pre> + +<p>A <a href="web.html#quotes">crypto quotes</a> page attributes this to <a +href="http://www.scramdisk.clara.net/">Sam Simpson</a>.</p> + +<p>There is an excellent paper available on <a +href="http://www.cdt.org/crypto/risks98/">Risks of Escrowed Encryption</a>, +from a group of cryptographic luminaries which included our project +leader.</p> + +<p>Like any unnecessary complication, GAK tends to weaken security of any +design it infects. For example:</p> +<ul> + <li>Matt Blaze found a fatal flaw in the US government's Clipper chip + shortly after design information became public. See his paper "Protocol + Failure in the Escrowed Encryption Standard" on his <a + href="http://www.crypto.com/papers/">papers</a> page.</li> + <li>a rather <a href="http://www.pgp.com/other/advisories/adk.asp">nasty + bug</a> was found in the "additional decryption keys" "feature" of some + releases of <a href="glossary.html#PGP">PGP</a></li> +</ul> + +<p>FreeS/WAN does not support escrowed encryption, and never will.</p> + +<h3><a name="shortkeys">Limited key lengths</a></h3> + +<p>Various governments, and some vendors, have also made persistent attempts +to convince people that:</p> +<ul> + <li>weak systems are sufficient for some data</li> + <li>strong cryptography should be reserved for cases where the extra + overheads are justified</li> +</ul> + +<p><strong>This is utter nonsense</strong>.</p> + +<p>Weak systems touted include:</p> +<ul> + <li>the ludicrously weak (deliberately crippled) 40-bit ciphers that until + recently were all various <a href="#exlaw">export laws</a> allowed</li> + <li>56-bit single DES, discussed <a href="#desnotsecure">below</a></li> + <li>64-bit symmetric ciphers and 512-bit RSA, the maximums for unrestricted + export under various current laws</li> +</ul> + +<p>The notion that choice of ciphers or keysize should be determined by a +trade-off between security requirements and overheads is pure bafflegab.</p> +<ul> + <li>For most <a href="glossary.html#symmetric">symmetric ciphers</a>, it is + simply a lie. Any block cipher has some natural maximum keysize inherent + in the design -- 128 bits for <a href="glossary.html#IDEA">IDEA</a> or <a + href="glossary.html#CAST128">CAST-128</a>, 256 for Serpent or Twofish, + 448 for <a href="glossary.html#Blowfish">Blowfish</a> and 2048 for <a + href="glossary.html#RC4">RC4</a>. Using a key size smaller than that + limit gives <em>exactly zero </em>savings in overhead. The crippled + 40-bit or 64-bit version of the cipher provides <em>no advantage + whatsoever</em>.</li> + <li><a href="glossary.html#AES">AES</a> uses 10 rounds with 128-bit keys, + 12 rounds for 192-bit and 14 rounds for 256-bit, so there actually is a + small difference in overhead, but not enough to matter in most + applications.</li> + <li>For <a href="glossary.html#3DES">triple DES</a> there is a grain of + truth in the argument. 3DES is indeed three times slower than single DES. + However, the solution is not to use the insecure single DES, but to pick + a faster secure cipher. <a href="glossary.html#CAST128">CAST-128</a>, <a + href="glossary.html#Blowfish">Blowfish</a> and the <a + href="glossary.html#AES">AES candidate</a> ciphers are are all + considerably faster in software than DES (let alone 3DES!), and + apparently secure.</li> + <li>For <a href="glossary.html#public">public key</a> techniques, there are + extra overheads for larger keys, but they generally do not affect overall + performance significantly. Practical public key applications are usually + <a href="glossary.html#hybrid">hybrid</a> systems in which the bulk of + the work is done by a symmetric cipher. The effect of increasing the cost + of the public key operations is typically negligible because the public + key operations use only a tiny fraction of total resources. + <p>For example, suppose public key operations use use 1% of the time in a + hybrid system and you triple the cost of public key operations. The cost + of symmetric cipher operations is unchanged at 99% of the original total + cost, so the overall effect is a jump from 99 + 1 = 100 to 99 + 3 = 102, + a 2% rise in system cost.</p> + </li> +</ul> + +<p>In short, <strong>there has never been any technical reason to use +inadequate ciphers</strong>. The only reason there has ever been for anyone +to use such ciphers is that government agencies want weak ciphers used so +that they can crack them. The alleged savings are simply propaganda.</p> +<pre> Mary had a little key (It's all she could export), + and all the email that she sent was opened at the Fort.</pre> + +<p>A <a href="web.html#quotes">crypto quotes</a> page attributes this to <a +href="http://theory.lcs.mit.edu:80/~rivest/">Ron Rivest</a>. NSA headquarters +is at Fort Meade, Maryland.</p> + +<p>Our policy in FreeS/WAN is to use only cryptographic components with +adequate keylength and no known weaknesses.</p> +<ul> + <li>We do not implement single DES because it is clearly <a + href="#desnotsecure">insecure</a>, so implemeting it would violate our + policy of avoiding bogus security. Our default cipher is <a + href="glossary.html#3DES">3DES</a></li> + <li>Similarly, we do not implement the 768-bit Group 1 for <a + href="glossary.html#DH">Diffie-Hellman</a> key negotiation. We provide + only the 1024-bit Group 2 and 1536-bit Group 5.</li> +</ul> + +<p>Detailed discussion of which IPsec features we implement or omit is in out +<a href="compat.html">compatibility document</a>.</p> + +<p>These decisions imply that we cannot fully conform to the IPsec RFCs, +since those have DES as the only required cipher and Group 1 as the only +required DH group. (In our view, the standards were subverted into offerring +bogus security.) Fortunately, we can still interoperate with most other IPsec +implementations since nearly all implementers provide at least 3DES and Group +2 as well.</p> + +<p>We hope that eventually the RFCs will catch up with our (and others') +current practice and reject dubious components. Some of our team and a number +of others are working on this in <a href="glossary.html#IETF">IETF</a> +working groups.</p> + +<h4>Some real trade-offs</h4> + +<p>Of course, making systems secure does involve costs, and trade-offs can be +made between cost and security. However, the real trade-offs have nothing to +do with using weaker ciphers.</p> + +<p>There can be substantial hardware and software costs. There are often +substantial training costs, both to train administrators and to increase user +awareness of security issues and procedures. There are almost always +substantial staff or contracting costs.</p> + +<p>Security takes staff time for planning, implementation, testing and +auditing. Some of the issues are subtle; you need good (hence often +expensive) people for this. You also need people to monitor your systems and +respond to problems. The best safe ever built is insecure if an attacker can +work on it for days without anyone noticing. Any computer is insecure if the +administrator is "too busy" to check the logs.</p> + +<p>Moreover, someone in your organisation (or on contract to it) needs to +spend considerable time keeping up with new developments. EvilDoers +<em>will</em> know about new attacks shortly after they are found. You need +to know about them before your systems are attacked. If your vendor provides +a patch, you need to apply it. If the vendor does nothing, you need to +complain or start looking for another vendor.</p> + +<p>For a fairly awful example, see this <a +href="http://www.sans.org/newlook/alerts/NTE-bank.htm">report</a>. In that +case over a million credit card numbers were taken from e-commerce sites, +using security flaws in Windows NT servers. Microsoft had long since released +patches for most or all of the flaws, but the site administrators had not +applied them.</p> + +<p>At an absolute minimum, you must do something about such issues +<em>before</em> an exploitation tool is posted to the net for downloading by +dozens of "script kiddies". Such a tool might appear at any time from the +announcement of the security hole to several months later. Once it appears, +anyone with a browser and an attitude can break any system whose +administrators have done nothing about the flaw.</p> + +<p>Compared to those costs, cipher overheads are an insignificant factor in +the cost of security.</p> + +<p>The only thing using a weak cipher can do for you is to cause all your +other investment to be wasted.</p> + +<h2><a name="exlaw">Cryptography Export Laws</a></h2> + +<p>Many nations restrict the export of cryptography and some restrict its use +by their citizens or others within their borders.</p> + +<h3><a name="USlaw">US Law</a></h3> + +<p>US laws, as currently interpreted by the US government, forbid export of +most cryptographic software from the US in machine-readable form without +government permission. In general, the restrictions apply even if the +software is widely-disseminated or public-domain and even if it came from +outside the US originally. Cryptography is legally a munition and export is +tightly controlled under the <a href="glossary.html#EAR">EAR</a> Export +Administration Regulations.</p> + +<p>If you are a US citizen, your brain is considered US territory no matter +where it is physically located at the moment. The US believes that its laws +apply to its citizens everywhere, not just within the US. Providing technical +assistance or advice to foreign "munitions" projects is illegal. The US +government has very little sense of humor about this issue and does not +consider good intentions to be sufficient excuse. Beware.</p> + +<p>The <a href="http://www.bxa.doc.gov/Encryption/">official website</a> for +these regulations is run by the Commerce Department's Bureau of Export +Administration (BXA).</p> + +<p>The <a href="http://www.eff.org/bernstein/">Bernstein case</a> challenges +the export restrictions on Constitutional grounds. Code is speech so +restrictions on export of code violate the First Amendment's free speech +provisions. This argument has succeeded in two levels of court so far. It is +quite likely to go on to the Supreme Court.</p> + +<p>The regulations were changed substantially in January 2000, apparently as +a government attempt to get off the hook in the Bernstein case. It is now +legal to export public domain source code for encryption, provided you notify +the <a href="glossary.html#BXA">BXA</a>.</p> + +<p>There are, however, still restrictions in force. + Moreover, the regulations can still be changed again whenever the government +chooses to do so. Short of a Supreme Court ruling (in the Berstein case or +another) that overturns the regulations completely, the problem of export +regulation is not likely to go away in the forseeable future.</p> + +<h4><a name="UScontrib">US contributions to FreeS/WAN</a></h4> + +<p>The FreeS/WAN project <strong>cannot accept software contributions, <em> +not even small bug fixes</em>, from US citizens or residents</strong>. We +want it to be absolutely clear that our distribution is not subject to US +export law. Any contribution from an American might open that question to a +debate we'd prefer to avoid. It might also put the contributor at serious +legal risk.</p> + +<p>Of course Americans can still make valuable contributions (many already +have) by reporting bugs, or otherwise contributing to discussions, on the +project <a href="mail.html">mailing list</a>. Since the list is public, this +is clearly constitutionally protected free speech.</p> + +<p>Note, however, that the export laws restrict Americans from providing +technical assistance to foreign "munitions" projects. The government might +claim that private discussions or correspondence with FreeS/WAN developers +were covered by this. It is not clear what the courts would do with such a +claim, so we strongly encourage Americans to use the list rather than risk +the complications.</p> + +<h3><a name="wrong">What's wrong with restrictions on cryptography</a></h3> + +<p>Some quotes from prominent cryptography experts:</p> + +<blockquote> + The real aim of current policy is to ensure the continued effectiveness of + US information warfare assets against individuals, businesses and + governments in Europe and elsewhere.<br> + <a href="http://www.cl.cam.ac.uk/users/rja14"> Ross Anderson, Cambridge + University</a></blockquote> + +<blockquote> + If the government were honest about its motives, then the debate about + crypto export policy would have ended years ago.<br> + <a href="http://www.counterpane.com"> Bruce Schneier, Counterpane + Systems</a></blockquote> + +<blockquote> + The NSA regularly lies to people who ask it for advice on export control. + They have no reason not to; accomplishing their goal by any legal means is + fine by them. Lying by government employees is legal.<br> + John Gilmore.</blockquote> + +<p>The Internet Architecture Board (IAB) and the Internet Engineering +Steering Group (IESG) made a <a href="iab-iesg.stmt">strong statement</a> in +favour of worldwide access to strong cryptography. Essentially the same +statement is in the appropriately numbered <a +href="ftp://ftp.isi.edu/in-notes/rfc1984.txt">RFC 1984</a>. Two critical +paragraphs are:</p> + +<blockquote> + ... various governments have actual or proposed policies on access to + cryptographic technology ... + + <p>(a) ... export controls ...<br> + (b) ... short cryptographic keys ...<br> + (c) ... keys should be in the hands of the government or ...<br> + (d) prohibit the use of cryptology ...</p> + + <p>We believe that such policies are against the interests of consumers and + the business community, are largely irrelevant to issues of military + security, and provide only a marginal or illusory benefit to law + enforcement agencies, ...</p> + + <p>The IAB and IESG would like to encourage policies that allow ready + access to uniform strong cryptographic technology for all Internet users in + all countries.</p> +</blockquote> + +<p>Our goal in the FreeS/WAN project is to build just such "strong +cryptographic technology" and to distribute it "for all Internet users in all +countries".</p> + +<p>More recently, the same two bodies (IESG and IAB) have issued <a +href="ftp://ftp.isi.edu/in-notes/rfc2804.txt">RFC 2804</a> on why the IETF +should not build wiretapping capabilities into protocols for the convenience +of security or law enforcement agenicies. The abstract from that document +is:</p> + +<blockquote> + The Internet Engineering Task Force (IETF) has been asked to take a + position on the inclusion into IETF standards-track documents of + functionality designed to facilitate wiretapping. + + <p>This memo explains what the IETF thinks the question means, why its + answer is "no", and what that answer means.</p> +</blockquote> +A quote from the debate leading up to that RFC: + +<blockquote> + We should not be building surveillance technology into standards. Law + enforcement was not supposed to be easy. Where it is easy, it's called a + police state.<br> + Jeff Schiller of MIT, in a discussion of FBI demands for wiretap capability + on the net, as quoted by <a + href="http://www.wired.com/news/politics/0,1283,31895,00.html">Wired</a>.</blockquote> + +<p>The <a href="http://www.ietf.org/mailman/listinfo/raven">Raven</a> mailing +list was set up for this IETF discussion.</p> + +<p>Our goal is to go beyond that RFC and prevent Internet wiretapping +entirely.</p> + +<h3><a name="Wassenaar">The Wassenaar Arrangement</a></h3> + +<p>Restrictions on the export of cryptography are not just US policy, though +some consider the US at least partly to blame for the policies of other +nations in this area.</p> + +<p>A number of countries:</p> + +<p>Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic, +Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, +Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic of +Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden, +Switzerland, Turkey, Ukraine, United Kingdom and United States</p> + +<p>have signed the Wassenaar Arrangement which restricts export of munitions +and other tools of war. Cryptographic sofware is covered there.</p> + +<p>Wassenaar details are available from the <a +href="http://www.wassenaar.org/"> Wassenaar Secretariat</a>, and elsewhere in +a more readable <a href="http://www.fitug.de/news/wa/index.html"> HTML +version</a>.</p> + +<p>For a critique see the <a href="http://www.gilc.org/crypto/wassenaar"> +GILC site</a>:</p> + +<blockquote> + The Global Internet Liberty Campaign (GILC) has begun a campaign calling + for the removal of cryptography controls from the Wassenaar Arrangement. + + <p>The aim of the Wassenaar Arrangement is to prevent the build up of + military capabilities that threaten regional and international security and + stability . . .</p> + + <p>There is no sound basis within the Wassenaar Arrangement for the + continuation of any export controls on cryptographic products.</p> +</blockquote> + +<p>We agree entirely.</p> + +<p>An interesting analysis of Wassenaar can be found on the <a +href="http://www.cyber-rights.org/crypto/wassenaar.htm">cyber-rights.org</a> +site.</p> + +<h3><a name="status">Export status of Linux FreeS/WAN</a></h3> + +<p>We believe our software is entirely exempt from these controls since the +Wassenaar <a +href="http://www.wassenaar.org/list/GTN%20and%20GSN%20-%2099.pdf">General +Software Note</a> says:</p> + +<blockquote> + The Lists do not control "software" which is either: + <ol> + <li>Generally available to the public by . . . retail . . . or</li> + <li>"In the public domain".</li> + </ol> +</blockquote> + +<p>There is a note restricting some of this, but it is a sub-heading under +point 1, so it appears not to apply to public domain software.</p> + +<p>Their glossary defines "In the public domain" as:</p> + +<blockquote> + . . . "technology" or "software" which has been made available without + restrictions upon its further dissemination. + + <p>N.B. Copyright restrictions do not remove "technology" or "software" + from being "in the public domain".</p> +</blockquote> + +<p>We therefore believe that software freely distributed under the <a +href="glossary.html#GPL">GNU Public License</a>, such as Linux FreeS/WAN, is +exempt from Wassenaar restrictions.</p> + +<p>Most of the development work is being done in Canada. Our understanding is +that the Canadian government accepts this interpretation.</p> +<ul> + <li>A web statement of <a + href="http://www.dfait-maeci.gc.ca/~eicb/notices/ser113-e.htm"> Canadian + policy</a> is available from the Department of Foreign Affairs and + International Trade.</li> + <li>Another document from that department states that <a + href="http://www.dfait-maeci.gc.ca/~eicb/export/gr1_e.htm">public domain + software</a> is exempt from the export controls.</li> + <li>A researcher's <a + href="http://insight.mcmaster.ca/org/efc/pages/doc/crypto-export.html">analysis</a> + of Canadian policy is also available.</li> +</ul> + +<p>Recent copies of the freely modifiable and distributable source code exist +in many countries. Citizens all over the world participate in its use and +evolution, and guard its ongoing distribution. Even if Canadian policy were +to change, the software would continue to evolve in countries which do not +restrict exports, and would continue to be imported from there into unfree +countries. "The Net culture treats censorship as damage, and routes around +it."</p> + +<h3><a name="help">Help spread IPsec around</a></h3> + +<p>You can help. If you don't know of a Linux FreeS/WAN archive in your own +country, please download it now to your personal machine, and consider making +it publicly accessible if that doesn't violate your own laws. If you have the +resources, consider going one step further and setting up a mirror site for +the whole <a href="intro.html#munitions">munitions</a> Linux crypto software +archive.</p> + +<p>If you make Linux CD-ROMs, please consider including this code, in a way +that violates no laws (in a free country, or in a domestic-only CD +product).</p> + +<p>Please send a note about any new archive mirror sites or CD distributions +to linux-ipsec@clinet.fi so we can update the documentation.</p> + +<p>Lists of current <a href="intro.html#sites">mirror sites</a> and of <a +href="intro.html#distwith">distributions</a> which include FreeS/WAN are in +our introduction section.</p> + +<h2><a name="desnotsecure">DES is Not Secure</a></h2> + +<p>DES, the <strong>D</strong>ata <strong>E</strong>ncryption +<strong>S</strong>tandard, can no longer be considered secure. While no major +flaws in its innards are known, it is fundamentally inadequate because its +<strong>56-bit key is too short</strong>. It is vulnerable to <a +href="glossary.html#brute">brute-force search</a> of the whole key space, +either by large collections of general-purpose machines or even more quickly +by specialized hardware. Of course this also applies to <strong>any other +cipher with only a 56-bit key</strong>. The only reason anyone could have for +using a 56 or 64-bit key is to comply with various <a +href="exportlaw.html">export laws</a> intended to ensure the use of breakable +ciphers.</p> + +<p>Non-government cryptologists have been saying DES's 56-bit key was too +short for some time -- some of them were saying it in the 70's when DES +became a standard -- but the US government has consistently ridiculed such +suggestions.</p> + +<p>A group of well-known cryptographers looked at key lengths in a <a +href="http://www.counterpane.com/keylength.html"> 1996 paper</a>. They +suggested a <em>minimum</em> of 75 bits to consider an existing cipher secure +and a <em>minimum of 90 bits for new ciphers</em>. More recent papers, +covering both <a href="glossary.html#symmetric">symmetric</a> and <a +href="glossary.html#public">public key</a> systems are at <a +href="http://www.cryptosavvy.com/">cryptosavvy.com</a> and <a +href="http://www.rsasecurity.com/rsalabs/bulletins/bulletin13.html">rsa.com</a>. +For all algorithms, the minimum keylengths recommended in such papers are +significantly longer than the maximums allowed by various export laws.</p> + +<p>In a <a +href="http://www.privacy.nb.ca/cryptography/archives/cryptography/html/1998-09/0095.html">1998 +ruling</a>, a German court described DES as "out-of-date and not safe enough" +and held a bank liable for using it.</p> + +<h3><a name="deshware">Dedicated hardware breaks DES in a few days</a></h3> + +<p>The question of DES security has now been settled once and for all. In +early 1998, the <a href="http://www.eff.org/">Electronic Frontier +Foundation</a> built a <a +href="http://www.eff.org/descracker.html">DES-cracking machine</a>. It can +find a DES key in an average of a few days' search. The details of all this, +including complete code listings and complete plans for the machine, have +been published in <a href="biblio.html#EFF"><cite>Cracking DES</cite></a>, by +the Electronic Frontier Foundation.</p> + +<p>That machine cost just over $200,000 to design and build. "Moore's Law" is +that machines get faster (or cheaper, for the same speed) by roughly a factor +of two every 18 months. At that rate, their $200,000 in 1998 becomes $50,000 +in 2001.</p> + +<p>However, Moore's Law is not exact and the $50,000 estimate does not allow +for the fact that a copy based on the published EFF design would cost far +less than the original. We cannot say exactly what such a cracker would cost +today, but it would likely be somewhere between $10,000 and $100,000.</p> + +<p>A large corporation could build one of these out of petty cash. The cost +is low enough for a senior manager to hide it in a departmental budget and +avoid having to announce or justify the project. Any government agency, from +a major municipal police force up, could afford one. Or any other group with +a respectable budget -- criminal organisations, political groups, labour +unions, religious groups, ... Or any millionaire with an obsession or a +grudge, or just strange taste in toys.</p> + +<p>One might wonder if a private security or detective agency would have one +for rent. They wouldn't need many clients to pay off that investment.</p> + +<h3><a name="spooks">Spooks may break DES faster yet</a></h3> + +<p>As for the security and intelligence agencies of various nations, they may +have had DES crackers for years, and theirs may be much faster. It is +difficult to make most computer applications work well on parallel machines, +or to design specialised hardware to accelerate them. Cipher-cracking is one +of the very few exceptions. It is entirely straightforward to speed up +cracking by just adding hardware. Within very broad limits, you can make it +as fast as you like if you have the budget. The EFF's $200,000 machine breaks +DES in a few days. An <a href="http://www.planepage.com/">aviation +website</a> gives the cost of a B1 bomber as $200,000,000. Spending that +much, an intelligence agency could break DES in an average time of <em>six +and a half minutes</em>.</p> + +<p>That estimate assumes they use the EFF's 1998 technology and just spend +more money. They may have an attack that is superior to brute force, they +quite likely have better chip technology (Moore's law, a bigger budget, and +whatever secret advances they may have made) and of course they may have +spent the price of an aircraft carrier, not just one aircraft.</p> + +<p>In short, we have <em>no idea</em> how quickly these organisations can +break DES. Unless they're spectacularly incompetent or horribly underfunded, +they can certainly break it, but we cannot guess how quickly. Pick any time +unit between days and milliseconds; none is entirely unbelievable. More to +the point, none of them is of any comfort if you don't want such +organisations reading your communications.</p> + +<p>Note that this may be a concern even if nothing you do is a threat to +anyone's national security. An intelligence agency might well consider it to +be in their national interest for certain companies to do well. If you're +competing against such companies in a world market and that agency can read +your secrets, you have a serious problem.</p> + +<p>One might wonder about technology the former Soviet Union and its allies +developed for cracking DES during the Cold War. They must have tried; the +cipher was an American standard and widely used. Certainly those countries +have some fine mathematicians, and those agencies had budget. How well did +they succeed? Is their technology now for sale or rent?</p> + +<h3><a name="desnet">Networks break DES in a few weeks</a></h3> + +<p>Before the definitive EFF effort, DES had been cracked several times by +people using many machines. See this <a +href="http://www.distributed.net/pressroom/DESII-1-PR.html"> press +release</a> for example.</p> + +<p>A major corporation, university, or government department could break DES +by using spare cycles on their existing collection of computers, by +dedicating a group of otherwise surplus machines to the problem, or by +combining the two approaches. It might take them weeks or months, rather than +the days required for the EFF machine, but they could do it.</p> + +<p>What about someone working alone, without the resources of a large +organisation? For them, cracking DES will not be easy, but it may be +possible. A few thousand dollars buys a lot of surplus workstations. A pile +of such machines will certainly heat your garage nicely and might break DES +in a few months or years. Or enroll at a university and use their machines. +Or use an employer's machines. Or crack security somewhere and steal the +resources to crack a DES key. Or write a virus that steals small amounts of +resources on many machines. Or . . .</p> + +<p>None of these approaches are easy or break DES really quickly, but an +attacker only needs to find one that is feasible and breaks DES quickly +enough to be dangerous. How much would you care to bet that this will be +impossible if the attacker is clever and determined? How valuable is your +data? Are you authorised to risk it on a dubious bet?</p> + +<h3><a name="no_des">We disable DES</a></h3> + +<p>In short, it is now absolutely clear that <strong>DES is not +secure</strong> against</p> +<ul> + <li>any <strong>well-funded opponent</strong></li> + <li>any opponent (even a penniless one) with access (even stolen access) to + <strong>enough general purpose computers</strong></li> +</ul> + +<p>That is why <strong>Linux FreeS/WAN disables all transforms which use +plain DES</strong> for encryption.</p> + +<p>DES is in the source code, because we need DES to implement our default +encryption transform, <a href="glossary.html#3DES">Triple DES</a>. <strong>We +urge you not to use single DES</strong>. We do not provide any easy way to +enable it in FreeS/WAN, and our policy is to provide no assistance to anyone +wanting to do so.</p> + +<h3><a name="40joke">40-bits is laughably weak</a></h3> + +<p>The same is true, in spades, of ciphers -- DES or others -- crippled by +40-bit keys, as many ciphers were required to be until recently under various +<a href="#exlaw">export laws</a>. A brute force search of such a cipher's +keyspace is 2<sup>16</sup> times faster than a similar search against DES. +The EFF's machine can do a brute-force search of a 40-bit key space in +<em>seconds</em>. One contest to crack a 40-bit cipher was won by a student +<a href="http://catless.ncl.ac.uk/Risks/18.80.html#subj1"> using a few +hundred idle machines at his university</a>. It took only three and half +hours.</p> + +<p>We do not, and will not, implement any 40-bit cipher.</p> + +<h3><a name="altdes">Triple DES is almost certainly secure</a></h3> + +<p><a href="glossary.html#3DES">Triple DES</a>, usually abbreviated 3DES, +applies DES three times, with three different keys. DES seems to be basically +an excellent cipher design; it has withstood several decades of intensive +analysis without any disastrous flaws being found. It's only major flaw is +that the small keyspace allows brute force attacks to succeeed. Triple DES +enlarges the key space to 168 bits, making brute-force search a ridiculous +impossibility.</p> + +<p>3DES is currently the only block cipher implemented in FreeS/WAN. 3DES is, +unfortunately, about 1/3 the speed of DES, but modern CPUs still do it at +quite respectable speeds. Some <a href="glossary.html#benchmarks">speed +measurements</a> for our code are available.</p> + +<h3><a name="aes.ipsec">AES in IPsec</a></h3> + +<p>The <a href="glossary.html#AES">AES</a> project has chosen a replacement +for DES, a new standard cipher for use in non-classified US government work +and in regulated industries such as banking. This cipher will almost +certainly become widely used for many applications, including IPsec.</p> + +<p>The winner, announced in October 2000 after several years of analysis and +discussion, was the <a +href="http://www.esat.kuleuven.ac.be/~rijmen/rijndael/">Rijndael</a> cipher +from two Belgian designers.</p> + +<p>It is almost certain that FreeS/WAN will add AES support. <a +href="web.html#patch">AES patches</a> are already available.</p> + +<h2><a name="press">Press coverage of Linux FreeS/WAN:</a></h2> + +<h3>FreeS/WAN 1.0 press</h3> +<ul> + <li><a + href="http://www.wired.com/news/news/technology/story/19136.html">Wired</a> + "Linux-Based Crypto Stops Snoops", James Glave April 15 1999</li> + <li><a + href="http://slashdot.org/articles/99/04/15/1851212.shtml">Slashdot</a></li> + <li><a href="http://dgl.com/itinfo/1999/it990415.html">DGL</a>, Damar Group + Limited; looking at FreeS/WAN from a perspective of business + computing</li> + <li><a href="http://linuxtoday.com/stories/5010.html">Linux Today</a></li> + <li><a href="http://www.tbtf.com/archive/1999-04-21.html#Tcep">TBTF</a>, + Tasty Bits from the Technology Front</li> + <li><a + href="http://www.salonmagazine.com/tech/log/1999/04/16/encryption/index.html">Salon + Magazine</a> "Free Encryption Takes a Big Step"</li> +</ul> + +<h3><a name="release">Press release for version 1.0</a></h3> +<pre> Strong Internet Privacy Software Free for Linux Users Worldwide + +Toronto, ON, April 14, 1999 - + +The Linux FreeS/WAN project today released free software to protect +the privacy of Internet communications using strong encryption codes. +FreeS/WAN automatically encrypts data as it crosses the Internet, to +prevent unauthorized people from receiving or modifying it. One +ordinary PC per site runs this free software under Linux to become a +secure gateway in a Virtual Private Network, without having to modify +users' operating systems or application software. The project built +and released the software outside the United States, avoiding US +government regulations which prohibit good privacy protection. +FreeS/WAN version 1.0 is available immediately for downloading at +http://www.xs4all.nl/~freeswan/. + +"Today's FreeS/WAN release allows network administrators to build +excellent secure gateways out of old PCs at no cost, or using a cheap +new PC," said John Gilmore, the entrepreneur who instigated the +project in 1996. "They can build operational experience with strong +network encryption and protect their users' most important +communications worldwide." + +"The software was written outside the United States, and we do not +accept contributions from US citizens or residents, so that it can be +freely published for use in every country," said Henry Spencer, who +built the release in Toronto, Canada. "Similar products based in the +US require hard-to-get government export licenses before they can be +provided to non-US users, and can never be simply published on a Web +site. Our product is freely available worldwide for immediate +downloading, at no cost." + +FreeS/WAN provides privacy against both quiet eavesdropping (such as +"packet sniffing") and active attempts to compromise communications +(such as impersonating participating computers). Secure "tunnels" carry +information safely across the Internet between locations such as a +company's main office, distant sales offices, and roaming laptops. This +protects the privacy and integrity of all information sent among those +locations, including sensitive intra-company email, financial transactions +such as mergers and acquisitions, business negotiations, personal medical +records, privileged correspondence with lawyers, and information about +crimes or civil rights violations. The software will be particularly +useful to frequent wiretapping targets such as private companies competing +with government-owned companies, civil rights groups and lawyers, +opposition political parties, and dissidents. + +FreeS/WAN provides privacy for Internet packets using the proposed +standard Internet Protocol Security (IPSEC) protocols. FreeS/WAN +negotiates strong keys using Diffie-Hellman key agreement with 1024-bit +keys, and encrypts each packet with 168-bit Triple-DES (3DES). A modern +$500 PC can set up a tunnel in less than a second, and can encrypt +6 megabits of packets per second, easily handling the whole available +bandwidth at the vast majority of Internet sites. In preliminary testing, +FreeS/WAN interoperated with 3DES IPSEC products from OpenBSD, PGP, SSH, +Cisco, Raptor, and Xedia. Since FreeS/WAN is distributed as source code, +its innards are open to review by outside experts and sophisticated users, +reducing the chance of undetected bugs or hidden security compromises. + +The software has been in development for several years. It has been +funded by several philanthropists interested in increased privacy on +the Internet, including John Gilmore, co-founder of the Electronic +Frontier Foundation, a leading online civil rights group. + +Press contacts: +Hugh Daniel, +1 408 353 8124, hugh@toad.com +Henry Spencer, +1 416 690 6561, henry@spsystems.net + +* FreeS/WAN derives its name from S/WAN, which is a trademark of RSA Data + Security, Inc; used by permission.</pre> +</body> +</html> diff --git a/doc/src/quickstart-configs.html b/doc/src/quickstart-configs.html new file mode 100644 index 000000000..b2ad21bcc --- /dev/null +++ b/doc/src/quickstart-configs.html @@ -0,0 +1,144 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>Quick FreeS/WAN installation and configuration</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, installation, quickstart"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Revised by Claudia Schmeing for same + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + This is a new file derived from: + RCS ID: $Id: quickstart-configs.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> +<BODY> +<H1><A name="quick_configs">FreeS/WAN quick start examples</A></H1> +<P>These are sample +<A href="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A> +configuration files for opportunistic encryption, with comments. Much of +this configuration will be unnecessary with the new defaults proposed +for FreeS/WAN 2.x.</P> +<P>Full instructions are in our +<A href="quickstart.html#quickstart">quickstart guide</A>. + +<H2><A name="qc.opp.client">Configuration for Initiate-only Opportunistic Encryption</A></H2> +<P>The ipsec.conf file for an initiate-only opportunistic setup is:</P> +<PRE># general IPsec setup +config setup + # Use the default interface + interfaces=%defaultroute + # Use auto= parameters in conn descriptions to control startup actions. + plutoload=%search + plutostart=%search + uniqueids=yes + +# defaults for subsequent connection descriptions +conn %default + # How to authenticate gateways + authby=rsasig + # default is + # load connection description into Pluto's database + # so it can respond if another gatway initiates + # individual connection descriptions may override this + auto=add + +# description for opportunistic connections +conn me-to-anyone + left=%defaultroute # all connections should use default route + right=%opportunistic # anyone we can authenticate + leftrsasigkey=%dnsondemand # NEW: look up keys in DNS as-needed + rightrsasigkey=%dnsondemand # (not at connection load time) + rekey=no # let unused connections die + keylife=1h # short + auto=route # set up for opportunistic + leftid=@xy.example.com # our identity for IPSec negotiations + # must match DNS and ipsec.secrets</PRE> + +<P>Normally, you need to do only two things:</P> +<UL> + <LI>edit <VAR>leftid=</VAR></LI> + <LI>set <VAR>auto=route</VAR></LI> +</UL> +<P> + However, some people may need to customize the <VAR>interfaces=</VAR> line + in the "config setup" section. All other sections are identical for any + standalone machine doing opportunistic encryption.</P> +<P>The @ sign in the <VAR>leftid=</VAR> makes the ID go "over the wire" + as a Fully Qualified Domain Name (FQDN). Without it, an IP address would + be used and this won't work.</P> +<P>The conn is not used to supply either public key. Your private key + is in <A href="manpage.d/ipsec.secrets.5.html">ipsec.secrets(5)</A> + and, for opportunistic encryption, the public keys for remote gateways + are all looked up in DNS.</P> +<P>FreeS/WAN authenticates opportunistic encryption by <A href="#gen_rsa">RSA + signature</A> only, so "public key" and "private key" refer to these keys.</P> +<P>While the <VAR>left</VAR> and <VAR>right</VAR> designations + here are arbitrary, we follow a convention of using <VAR>left</VAR> for + local and <VAR>right</VAR> for remote.</P> + +<P><A href="quickstart.html#config.opp.client">Continue configuring +initiate-only opportunism.</A> + +<H2><A name="qc.incoming.opp.conf">ipsec.conf for Incoming Opportunistic Encryption</A></H2> +Use the ipsec.conf above, except that the section describing opportunistic +connections is now:</P> +<PRE> +# description for opportunistic connections +conn me-to-anyone + left=%defaultroute # all connections should use default route + right=%opportunistic # anyone we can authenticate + leftrsasigkey=%dnsondemand # NEW: look up keys in DNS as-needed + rightrsasigkey=%dnsondemand # (not at connection load time) + rekey=no # let unused connections die + keylife=1h # short + auto=route # set up for opportunistic</PRE> + +<P>Note that <VAR>leftid=</VAR> has been removed. With no explicit setting, +<VAR>leftid=</VAR> defaults to the IP of your public interface.</P> + +<P><A href="quickstart.html#incoming.opp.conf">Continue configuring +full opportunism.</A> + + +<H2><A name="qc.gate.opp.conf">ipsec.conf for Opportunistic Gateway</A></H2> +Use the ipsec.conf above, plus these connections: + +<PRE>conn subnet-to-anyone # must be above me-to-anyone + also=me-to-anyone + leftsubnet=42.42.42.0/24 + +conn me-to-anyone # just like for full opportunism + left=%defaultroute + right=%opportunistic + leftrsasigkey=%dnsondemand + rightrsasigkey=%dnsondemand + keylife=1h + rekey=no + auto=route # be sure this is enabled + # Note there is NO leftid= </PRE> + + +<P>Note that a subnet described in ipsec.conf(5) need not correspond to a + physical network segment. This is discussed in more detail in our +<A href="adv_config.html">advanced configuration</A> document.</P> + +<P>If required, a gateway can easily provide this service for more than one + subnet. You just add a connection description for each.</P> + +<P><A href="quickstart.html#config.opp.gate">Continue configuring an +opportunistic gateway.</A> + + +</BODY> +</HTML> + diff --git a/doc/src/quickstart-firewall.html b/doc/src/quickstart-firewall.html new file mode 100644 index 000000000..53c27b5af --- /dev/null +++ b/doc/src/quickstart-firewall.html @@ -0,0 +1,187 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>Quick FreeS/WAN installation and configuration</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, installation, quickstart"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Revised by Claudia Schmeing for same + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + RCS ID: $Id: quickstart-firewall.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> +<BODY> +<H1><A name="quick_firewall">FreeS/WAN quick start on firewalling</A></H1> +<P>This firewalling information supplements our +<A HREF="quickstart.html#quick_guide">quickstart guide.</A></P> +<P>It includes tips for firewalling:</P> +<UL> +<LI><A HREF="#firewall.standalone">a standalone system with initiator-only +opportunism</A></LI> +<LI><A HREF="#incoming.opp.firewall">incoming opportunistic connections</A></LI> +<LI><A HREF="#opp.gate.firewall">an opportunistic gateway</A></LI> +</UL> +<P>and a list of helpful <A HREF="#resources">resources</A>.</P> +<H2><A name="firewall.standalone">Firewalling a standalone system</A></H2> +<P>Firewall rules on a standalone system doing IPsec can be very simple.</P> +<P>The first step is to allow IPsec packets (IKE on UDP port 500 plus + ESP, protocol 50) in and out of your gateway. A script to set up + iptables(8) rules for this is:</P> +<PRE># edit this line to match the interface you use as default route +# ppp0 is correct for many modem, DSL or cable connections +# but perhaps not for you +world=ppp0 +# +# allow IPsec +# +# IKE negotiations +iptables -A INPUT -p udp -i $world --sport 500 --dport 500 -j ACCEPT +iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT +# ESP encryption and authentication +iptables -A INPUT -p 50 -i $world -j ACCEPT +iptables -A OUTPUT -p 50 -o $world -j ACCEPT</PRE> +<P>Optionally, you could restrict this, allowing these packets only to + and from a list of known gateways.</P> +<P>A second firewalling step -- access controls built into the IPsec + protocols -- is automatically applied:</P> +<DL> +<DT><A href="glossary.html#Pluto">Pluto</A> -- the FreeS/WAN keying + daemon -- deals with the IKE packets.</DT> +<DD>Pluto authenticates its partners during the IKE negotiation, and + drops negotiation if authentication fails.</DD> +<DT><A href="glossary.html#KLIPS">KLIPS</A> -- the FreeS/WAN kernel + component -- handles the ESP packets.</DT> +<DD> +<DL> +<DT>KLIPS drops outgoing packets</DT> +<DD>if they are routed to IPsec, but no tunnel has been negotiated for + them</DD> +<DT>KLIPS drops incoming unencrypted packets</DT> +<DD>if source and destination addresses match a tunnel; the packets + should have been encrypted</DD> +<DT>KLIPS drops incoming encrypted packets</DT> +<DD>if source and destination address do not match the negotiated + parameters of the tunnel that delivers them</DD> +<DD>if packet-level authentication fails</DD> +</DL> +</DD> +</DL> +<P>These errors are logged. See our <A href="trouble.html"> + troubleshooting</A> document for details.</P> +<P>As an optional third step, you may wish to filter packets emerging from + your opportunistic tunnels. + These packets arrive on an interface such as <VAR>ipsec0</VAR>, rather than + <VAR>eth0</VAR>, <VAR>ppp0</VAR> or whatever. For example, in an iptables(8) + rule set, you would use:</P> +<DL> +<DT><VAR>-i ipsec+</VAR></DT> +<DD>to specify packets arriving on any ipsec device</DD> +<DT><VAR>-o ipsec+</VAR></DT> +<DD>to specify packets leaving via any ipsec device</DD> +</DL> +<P>In this way, you can apply whatever additional filtering you like to these +packets.</P> +<P>The packets emerging on <VAR>ipsec0</VAR> are likely + to be things that a client application on your machine requested: web + pages, e-mail, file transfers and so on. However, any time you initiate + an opportunistic connection, you open a two-way connection to + another machine (or network). It is conceivable that a Bad Guy there + could take advantage of your link.</P> +<P>For more information, read the next section.</P> +</P> +<H2><A name="incoming.opp.firewall">Firewalling incoming opportunistic + connections</A></H2> +<P>The basic firewalling for IPsec does not change when you support + incoming connections as well as connections you initiate. You must + still allow IKE (UDP port 500) and ESP (protocol 50) packets to and + from your machine, as in the rules given <A href="#firewall.standalone"> + above</A>.</P> +<P>However, there is an additional security concern when you allow + incoming opportunistic connections. Incoming opportunistic packets + enter your machine via an IPSec tunnel. That is, they all appear as + ESP (protocol 50) packets, concealing whatever port and protocol + characteristics the packet within the tunnel has. Contained + in the tunnel as they pass through <VAR>ppp0</VAR> or <VAR>eth0</VAR>, + these packets can bypass your usual firewall rules on these interfaces. +<P>Consequently, you will want to firewall your <VAR>ipsec</VAR> interfaces + the way you would any publicly accessible interface.</P> +<P>A simple way to do this is to create one iptables(8) table with + all your filtering rules for incoming packets, and apply the entire table to + all public interfaces, including <VAR>ipsec</VAR> interfaces.</P> + +<H2><A name="opp.gate.firewall">Firewalling for opportunistic gateways</A></H2> +<P>On a gateway, the IPsec-related firewall rules applied for input and + output on the Internet side are exactly as shown +<A HREF="#firewall.standalone">above</A>. A gateway + exchanges exactly the same things -- UDP 500 packets and IPsec packets + -- with other gateways that a standalone system does, so it can use + exactly the same firewall rules as a standalone system would.</P> +<P>However, on a gateway there are additional things to do:</P> +<UL> +<LI>you have other interfaces and need rules for them</LI> +<LI>packets emerging from ipsec processing must be correctly forwarded</LI> +</UL> +<P>You need additional rules to handle these things. For example, adding + some rules to the set shown above we get:</P> +<PRE># edit this line to match the interface you use as default route +# ppp0 is correct for many modem, DSL or cable connections +# but perhaps not for you +world=ppp0 +# +# edit these lines to describe your internal subnet and interface +localnet=42.42.42.0/24 +internal=eth1 +# +# allow IPsec +# +# IKE negotiations +iptables -A INPUT -p udp -i $world --sport 500 --dport 500 -j ACCEPT +iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT +# ESP encryption and authentication +iptables -A INPUT -p 50 -i $world -j ACCEPT +iptables -A OUTPUT -p 50 -o $world -j ACCEPT +# +# packet forwarding for an IPsec gateway +# simplest possible rules +$ forward everything, with no attempt to filter +# +# handle packets emerging from IPsec +# ipsec+ means any of ipsec0, ipsec1, ... +iptables -A FORWARD -d $localnet -i ipsec+ -j ACCEPT +# simple rule for outbound packets +# let local net send anything +# IPsec will encrypt some of it +iptables -A FORWARD -s $localnet -i $internal -j ACCEPT </PRE> +<P>On a production gateway, you would no doubt need tighter rules than + the above.</P> +<H2><A NAME="resources">Firewall resources</A></H2> +<P>For more information, see these handy resources:</P> +<UL> +<LI><A href="http://www.netfilter.org/documentation/">netfilter + documentation</A></LI> +<LI>books such as: +<UL> +<LI>Cheswick and Bellovin, <A href="biblio.html#firewall.book">Firewalls + and Internet Security</A></LI> +<LI>Zeigler, <A href="biblio.html#Zeigler">Linux Firewalls</A>,</LI> +</UL> +</LI> +<LI><A href="firewall.html#firewall">our firewalls document</A></LI> +<LI><A href="web.html#firewall.web">our firewall links</A></LI> +</UL> +<A HREF="quickstart.html#quick.firewall">Back to our quickstart guide.</A> +</BODY> +</HTML> + + + diff --git a/doc/src/quickstart.html b/doc/src/quickstart.html new file mode 100644 index 000000000..a74c11774 --- /dev/null +++ b/doc/src/quickstart.html @@ -0,0 +1,458 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>Quick FreeS/WAN installation and configuration</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, installation, quickstart"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Revised by Claudia Schmeing for same + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: quickstart.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> +<BODY> +<H1><A name="quickstart">Quickstart Guide to Opportunistic Encryption</A></H1> +<A name="quick_guide"></A> + +<H2><A name="opp.setup">Purpose</A></H2> + +<P>This page will get you started using Linux FreeS/WAN with opportunistic + encryption (OE). OE enables you to set up IPsec tunnels + without co-ordinating with another + site administrator, and without hand configuring each tunnel. + If enough sites support OE, a "FAX effect" occurs, and + many of us can communicate without eavesdroppers.</P> + +<H3>OE "flag day"</H3> + +<P>As of FreeS/WAN 2.01, OE uses DNS TXT resource records (RRs) +only (rather than TXT with KEY). +This change causes a +<a href="http://jargon.watson-net.com/jargon.asp?w=flag+day">"flag day"</a>. +Users of FreeS/WAN 2.00 (or earlier) OE who are upgrading may require +additional resource records, as detailed in our +<a href="upgrading.html#upgrading.flagday">upgrading document</a>. +OE setup instructions here are for 2.02 or later.</P> + + +<H2><A name="opp.dns">Requirements</A></H2> + +<P>To set up opportunistic encryption, you will need:</P> +<UL> +<LI>a Linux box. For OE to the public Internet, this box must NOT +be behind <A HREF="glossary.html#NAT.gloss">Network Address Translation</A> +(NAT).</LI> +<LI>to install Linux FreeS/WAN 2.02 or later</LI> +<LI>either control over your reverse DNS (for full opportunism) or +the ability to write to some forward domain (for initiator-only). +<A HREF="http://www.fdns.net">This free DNS service</A> explicitly +supports forward TXT records for FreeS/WAN use.</LI> +<LI>(for full opportunism) a static IP</LI> +</UL> + +<P>Note: Currently, only Linux FreeS/WAN supports opportunistic +encryption.</P> + +<H2><A name="easy.install">RPM install</A></H2> + +<P>Our instructions are for a recent Red Hat with a 2.4-series stock or +Red Hat updated kernel. For other ways to install, see our +<A href="install.html#install">install document</A>.</P> + + +<H3>Download RPMs</H3> + +<P>If we have prebuilt RPMs for your Red Hat system, +this command will get them: +</P> + +<PRE> ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/`uname -r | tr -d 'a-wy-z'`/\*</PRE> + +<P>If that fails, you will need to try <A HREF="install.html">another install +method</A>. +Our kernel modules +<B>will only work on the Red Hat kernel they were built for</B>, +since they are very sensitive to small changes in the kernel.</P> + +<P>If it succeeds, you will have userland tools, a kernel module, and an +RPM signing key:</P> + +<PRE> freeswan-module-2.04_2.4.20_20.9-0.i386.rpm + freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm + freeswan-rpmsign.asc</PRE> + + +<H3>Check signatures</H3> + +<P>If you're running RedHat 8.x or later, import the RPM signing key into the +RPM database:</P> +<PRE> rpm --import freeswan-rpmsign.asc</PRE> + +<P>For RedHat 7.x systems, you'll need to add it to your +<A HREF="glossary.html#PGP">PGP</A> keyring:</P> +<PRE> pgp -ka freeswan-rpmsign.asc</PRE> + +<P>Check the digital signatures on both RPMs using:</P> +<PRE> rpm --checksig freeswan*.rpm </PRE> + +<P>You should see that these signatures are good:</P> +<PRE> freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK + freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK</PRE> + + +<H3>Install the RPMs</H3> + +<P>Become root:</P> +<PRE> su</PRE> + +<P>Install your RPMs with:<P> +<PRE> rpm -ivh freeswan*.rpm</PRE> + +<P>If you're upgrading from FreeS/WAN 1.x RPMs, and have problems with that +command, see +<A HREF="upgrading.html#upgrading.rpms">this note</A>.</P> + +<P>Then, start FreeS/WAN:</P> +<PRE> service ipsec start</PRE> + + +<H3><A name="testinstall">Test</A></H3> +<P>To check that you have a successful install, run:</P> +<PRE> ipsec verify</PRE> + +<P>You should see as part of the <var>verify</var> output:</P> +<PRE> + Checking your system to see if IPsec got installed and started correctly + Version check and ipsec on-path [OK] + Checking for KLIPS support in kernel [OK] + Checking for RSA private key (/etc/ipsec.secrets) [OK] + Checking that pluto is running [OK] + ...</PRE> + +<P>If any of these first four checks fails, see our +<A href="trouble.html#install.check">troubleshooting guide</A>. +</P> + +<H2><A name="opp.setups.list">Our Opportunistic Setups</A></H2> +<H3>Full or partial opportunism?</H3> +<P>Determine the best form of opportunism your system can support.</P> +<UL> +<LI>For <A HREF="#opp.incoming">full opportunism</A>, you'll need a static +IP and and either control over your reverse DNS or an ISP +that can add the required TXT record for you.</LI> +<LI>If you have a dynamic IP, and/or write access to forward DNS only, +you can do <A HREF="#opp.client">initiate-only opportunism</A></LI> +<LI>To protect traffic bound for real IPs behind your gateway, use +<A HREF="adv_config.html#opp.gate">this form of full opportunism</A>.</LI> +</UL> + +<H2><A name="opp.client">Initiate-only setup</A></H2> + +<H3>Restrictions</H3> +<P>When you set up initiate-only Opportunistic Encryption (iOE):</P> +<UL> +<LI>there will be <STRONG> no incoming connection requests</STRONG>; you + can initiate all the IPsec connections you need.</LI> +<LI><STRONG>only one machine is visible</STRONG> on your end of the + connection.</LI> +<LI>iOE also protects traffic on behalf of +<A HREF="glossary.html#NAT.gloss">NATted</A> hosts behind the iOE box.</LI> +</UL> +<P>You cannot network a group of initiator-only machines if none +of these is capable of responding to OE. If one is capable of responding, +you may be able to create a hub topology using routing.</P> + + +<H3><A name="forward.dns">Create and publish a forward DNS record</A></H3> + +<H4>Find a domain you can use</H4> + +<P>Find a DNS forward domain (e.g. example.com) where you can publish your key. +You'll need access to the DNS zone files for that domain. +This is common for a domain you own. Some free DNS providers, +such as <A HREF="http://www.fdns.net">this one</A>, also provide +this service.</P> + +<P>Dynamic IP users take note: the domain where you place your key + need not be associated with the IP address for your system, + or even with your system's usual hostname.</P> + +<H4>Choose your ID</H4> + +<P>Choose a name within that domain which you will use to identify your + machine. It's convenient if this can be the same as your hostname:</P> +<PRE> [root@xy root]# hostname --fqdn + xy.example.com</PRE> +<P>This name in FQDN (fully-qualified domain name) +format will be your ID, for DNS key lookup and IPsec +negotiation.</P> + + +<H4>Create a forward TXT record</H4> + +<P>Generate a forward TXT record containing your system's public key + with a command like:</P> +<PRE> ipsec showhostkey --txt @xy.example.com</PRE> +<P>using your chosen ID in place of +xy.example.com. +This command takes the contents of +/etc/ipsec.secrets and reformats it into something usable by ISC's BIND. + The result should look like this (with the key data trimmed down for + clarity):</P> +<PRE> + ; RSA 2192 bits xy.example.com Thu Jan 2 12:41:44 2003 + IN TXT "X-IPsec-Server(10)=@xy.example.com" + "AQOF8tZ2... ...+buFuFn/" +</PRE> + + +<H4>Publish the forward TXT record</H4> + +<P>Insert the record into DNS, or have a system adminstrator do it +for you. It may take up to 48 hours for the record to propagate, but +it's usually much quicker.</P> + +<H3>Test that your key has been published</H3> + +<P>Check your DNS work</P> + +<PRE> ipsec verify --host xy.example.com</PRE> + +<P>As part of the <var>verify</var> output, you ought to see something +like:</P> + +<PRE> ... + Looking for TXT in forward map: xy.example.com [OK] + ...</PRE> + +<P>For this type of opportunism, only the forward test is relevant; +you can ignore the tests designed to find reverse records.</P> + + +<H3>Configure, if necessary</H3> + +<P> +If your ID is the same as your hostname, +you're ready to go. +FreeS/WAN will use its +<A HREF="policygroups.html">built-in connections</A> to create +your iOE functionality. +</P> + +<P>If you have chosen a different ID, you must tell FreeS/WAN about it via +<A HREF="manpage.d/ipsec.conf.5.html"><VAR>ipsec.conf</VAR></A>: + +<PRE> config setup + myid=@myname.freedns.example.com</PRE> + +<P>and restart FreeS/WAN: +</P> +<PRE> service ipsec restart</PRE> +<P>The new ID will be applied to the built-in connections.</P> + +<P>Note: you can create more complex iOE configurations as explained in our +<A HREF="policygroups.html#policygroups">policy groups document</A>, or +disable OE using +<A HREF="policygroups.html#disable_policygroups">these instructions</A>.</P> + + +<H3>Test</H3> +<P>That's it! <A HREF="#opp.test">Test your connections</A>.</P> + +<A name="opp.incoming"></A><H2>Full Opportunism</H2> + +<P>Full opportunism +allows you to initiate and receive opportunistic connections on your +machine.</P> + +<A name="incoming.opp.dns"></A><H3>Put a TXT record in a Forward Domain</H3> + +<P>To set up full opportunism, first +<A HREF="#forward.dns">set up a forward TXT record</A> as for +<A HREF="#opp.client">initiator-only OE</A>, using +an ID (for example, your hostname) that resolves to your IP. Do not +configure <VAR>/etc/ipsec.conf</VAR>, but continue with the +instructions for full opportunism, below. +</P> + +<P>Note that this forward record is not currently necessary for full OE, +but will facilitate future features.</P> + + +<A name="incoming.opp.dns"></A><H3>Put a TXT record in Reverse DNS</H3> + +<P>You must be able to publish your DNS RR directly in the reverse domain. +FreeS/WAN will not follow a PTR which appears in the reverse, since +a second lookup at connection start time is too costly.</P> + + +<H4>Create a Reverse DNS TXT record</H4> + +<P>This record serves to publicize your FreeS/WAN public key. In + addition, it lets others know that this machine can receive opportunistic +connections, and asserts that the machine is authorized to encrypt on +its own behalf.</P> + +<P>Use the command:</P> +<PRE> ipsec showhostkey --txt 192.0.2.11</PRE> +<P>where you replace 192.0.2.11 with your public IP.</P> + +<P>The record (with key shortened) looks like:</P> +<PRE> ; RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000 + IN TXT "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"</PRE> + + +<H4>Publish your TXT record</H4> + +<P>Send these records to your ISP, to be published in your IP's reverse map. +It may take up to 48 hours for these to propagate, but usually takes +much less time.</P> + + +<H3>Test your DNS record</H3> + +<P>Check your DNS work with</P> + +<PRE> ipsec verify --host xy.example.com</PRE> + +<P>As part of the <var>verify</var> output, you ought to see something like:</P> + +<PRE> ... + Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK] + ...</PRE> + +<P>which indicates that you've passed the reverse-map test.</P> + +<H3>No Configuration Needed</H3> + +<P>FreeS/WAN 2.x ships with full OE enabled, so you don't need to configure +anything. +To enable OE out of the box, FreeS/WAN 2.x uses the policy group +<VAR>private-or-clear</VAR>, +which creates IPsec connections if possible (using OE if needed), +and allows traffic in the clear otherwise. You can create more complex +OE configurations as described in our +<A HREF="policygroups.html#policygroups">policy groups document</A>, or +disable OE using +<A HREF="policygroups.html#disable_policygroups">these instructions</A>.</P> + +<P>If you've previously configured for initiator-only opportunism, remove + <VAR>myid=</VAR> from <VAR>config setup</VAR>, so that peer FreeS/WANs +will look up your key by IP. Restart FreeS/WAN so that your change will +take effect, with</P> + +<PRE> service ipsec restart</PRE> + + +<H3>Consider Firewalling</H3> + +<P>If you are running a default install of RedHat 8.x, take note: you will +need to alter your iptables rule setup to allow IPSec traffic through your +firewall. See <A HREF="firewall.html#simple.rules">our firewall document</A> +for sample <VAR>iptables</VAR> rules.</P> + + +<H3>Test</H3> + +<P>That's it. Now, <A HREF="#opp.test">test your connection</A>. + + + + +<H3>Test</H3> + +<P>Instructions are in the next section.</P> + + +<H2><A NAME="opp.test">Testing opportunistic connections</A></H2> + +<P>Be sure IPsec is running. You can see whether it is with:</P> +<PRE> ipsec setup status</PRE> +<P>If need be, you can restart it with:</P> +<PRE> service ipsec restart</PRE> + +<P>Load a FreeS/WAN test website from the host on which you're running +FreeS/WAN. Note: the feds may be watching these sites. Type one of:<P> +<PRE> links oetest.freeswan.org</PRE> +<PRE> links oetest.freeswan.nl</PRE> +<!--<PRE> links oetest.freeswan.ca</PRE>--> + +<P>A positive result looks like this:</P> + +<PRE> + You seem to be connecting from: 192.0.2.11 which DNS says is: + gateway.example.com + _________________________________________________________________ + + Status E-route + OE enabled 16 192.139.46.73/32 -> 192.0.2.11/32 => + tun0x2097@192.0.2.11 + OE enabled 176 192.139.46.77/32 -> 192.0.2.11/32 => + tun0x208a@192.0.2.11 +</PRE> + +<P>If you see this, congratulations! Your OE host or gateway will now encrypt +its own traffic whenever it can. For more OE tests, please see our +<A HREF="testing.html#test.oe">testing document</A>. If you have difficulty, +see our <A HREF="#oe.trouble">OE troubleshooting tips</A>. +</P> + + + +<H2>Now what?</H2> + +<P>Please see our <A HREF="policygroups.html">policy groups document</A> +for more ways to set up Opportunistic Encryption.</P> + +<P>You may also wish to make some <A HREF="config.html"> +pre-configured connections</A>. +</P> + +<H2>Notes</H2> + +<UL> +<LI>We assume some facts about your system in order to make Opportunistic +Encryption easier to configure. For example, we assume that you wish +to have FreeS/WAN secure your default interface.</LI> +<LI>You may change this, and other settings, by altering the +<VAR>config setup</VAR> section in +<VAR>/etc/ipsec.conf</VAR>. +</LI> +<LI>Note that the built-in connections used to build policy groups do +not inherit from <VAR>conn default</VAR>.</LI> +<!-- +<LI>If you do not define your local identity +(eg. <VAR>leftid</VAR>), this will be the IP address of your default +FreeS/WAN interface. +--> +<LI> +If you fail to define your local identity and +do not fill in your reverse DNS entry, you will not be able to use OE.</LI> +</UL> + +<A NAME="oe.trouble"></A><H2>Troubleshooting OE</H2> + +<P>See the OE troubleshooting hints in our +<A HREF="trouble.html#oe.trouble">troubleshooting guide</A>. +</P> + +<A NAME="oe.known-issues"></A><H2>Known Issues</H2> + +<P>Please see +<A HREF="opportunism.known-issues">this list</A> of known issues +with Opportunistic Encryption.</P> + + +</BODY> +</HTML> diff --git a/doc/src/reference.ESPUDP.xml b/doc/src/reference.ESPUDP.xml new file mode 100644 index 000000000..c9b96cef3 --- /dev/null +++ b/doc/src/reference.ESPUDP.xml @@ -0,0 +1,34 @@ +<?xml version='1.0'?> +<!DOCTYPE reference SYSTEM 'rfc2629.dtd'> + +<reference anchor='ESPUDP'> + +<front> +<title abbrev='UDPESP'>UDP Encapsulation of IPsec Packets</title> +<author initials='A.' surname='Huttunen' fullname='Ari Huttunen'> +<organization>F-Secure Corporation</organization> +<address> +<postal> +<street>Tammasaarenkatu 7</street> +<street>FIN-00181 HELSINKI</street> +<country>Finland</country></postal> +<email>Ari.Huttunen@F-Secure.com</email></address></author> + +<author initials='W.' surname='Dixon' fullname='William Dixon'> +<organization>Microsoft</organization> +<address> +<postal> +<street>One Microsoft Way</street> +<street>Redmond</street> +<street>WA 98052</street> +<country>USA</country></postal> +<email>wdixon@microsoft.com</email></address></author> + +<date month='June' year='2001'></date> +<area>Security</area> +<keyword>IP security protocol</keyword> +<keyword>IPSEC</keyword> +<keyword>security</keyword></front> + +<seriesInfo name='ID' value='internet-draft (draft-ietf-ipsec-udp-encaps-00) (informative)' /> +</reference> diff --git a/doc/src/reference.KEYRESTRICT.xml b/doc/src/reference.KEYRESTRICT.xml new file mode 100644 index 000000000..62aa1ef96 --- /dev/null +++ b/doc/src/reference.KEYRESTRICT.xml @@ -0,0 +1,31 @@ +<?xml version='1.0'?> +<!DOCTYPE reference SYSTEM 'rfc2629.dtd'> + +<reference anchor='KEYRESTRICT'> + +<front> +<title abbrev='KEYRESTRICT'>Limiting the Scope of the KEY Resource Record</title> +<author initials='D.' surname='Massey' fullname='Dan Massey'> +<organization>USC/ISI</organization> +<address> +<postal> +<street>USC Informational Sciences Institute</street> +<street>3811 North Fairfax Drive, Suite 200</street> +<street>Arlington, VA 22203</street> +<country>USA</country></postal> +<email>masseyd@isi.edu</email></address></author> + +<author initials='S.' surname='Rose' fullname='Scott Rose'> +<organization>National Institute for Standards and Technology</organization> +<address> +<postal> +<street>Gaithersburg, MD</street> +<country>USA</country></postal> +<email>scott.rose@nist.gov</email></address></author> + +<date month='March' year='2002'></date> +<area>Internet</area> +</front> + +<seriesInfo name='ID' value='internet-draft (draft-ietf-dnsext-restrict-key-for-dnssec-02) (normative)' /> +</reference> diff --git a/doc/src/reference.MODPGROUPS.xml b/doc/src/reference.MODPGROUPS.xml new file mode 100644 index 000000000..5eaf83f89 --- /dev/null +++ b/doc/src/reference.MODPGROUPS.xml @@ -0,0 +1,32 @@ +<?xml version='1.0'?> +<!DOCTYPE reference SYSTEM 'rfc2629.dtd'> + +<reference anchor='MODPGROUPS'> + +<front> +<title abbrev='MODPGROUPS'>More MODP Diffie-Hellman groups for IKE</title> +<author initials='T.' surname='Kivinen' fullname='Tero Kivinen'> +<organization>SSH Communications Security</organization> +<address> +<postal> +<street>Fredrikinkatu 42</street> +<street>FIN-00100 HELSINKI</street> +<country>Finland</country></postal> +<email>kivinen@ssh.fi</email></address></author> + +<author initials='M.' surname='Kojo' fullname='Mika Kojo'> +<organization>University of Helsinki</organization> +<address> +<postal> +<street>HELSINKI</street> +<country>Finland</country></postal> +<email>mrskojo@cc.helsinki.fi</email></address></author> + +<date month='November' year='2001'></date> +<area>Security</area> +<keyword>IP security protocol</keyword> +<keyword>IPSEC</keyword> +<keyword>security</keyword></front> + +<seriesInfo name='ID' value='internet-draft (draft-ietf-ipsec-ike-modp-groups-03) (normative)' /> +</reference> diff --git a/doc/src/reference.OEspec.xml b/doc/src/reference.OEspec.xml new file mode 100644 index 000000000..29c6d6efd --- /dev/null +++ b/doc/src/reference.OEspec.xml @@ -0,0 +1,45 @@ +<?xml version='1.0'?> +<!DOCTYPE reference SYSTEM 'rfc2629.dtd'> + +<reference anchor='OEspec'> + +<front> +<title abbrev='OEspec'>Opportunistic Encryption</title> + + <author initials="D.H." surname="Redelmeier" + fullname="D. Hugh Redelmeier"> + <organization abbrev="Mimosa">Mimosa</organization> + <address> + <postal> + <street>Somewhere</street> + <city>Toronto</city> + <region>ON</region> + <country>CA</country> + </postal> + <email>hugh@mimosa.com</email> + </address> + </author> + + <author initials="H." surname="Spencer" + fullname="Henry Spencer"> + <organization abbrev="SP Systems">SP Systems</organization> + <address> + <postal> + <street>Box 280 Station A</street> + <city>Toronto</city> + <region>ON</region> + <code>M5W 1B2</code> + <country>Canada</country> + </postal> + <email>henry@spsystems.net</email> + </address> + </author> + +<date month='May' year='2001'></date> +<keyword>IP security protocol</keyword> +<keyword>IPSEC</keyword> +<keyword>security</keyword></front> + +<seriesInfo name='paper' value='http://www.freeswan.org/freeswan_trees/freeswan-1.91/doc/opportunism.spec' /> +</reference> + diff --git a/doc/src/reference.RFC.3526.xml b/doc/src/reference.RFC.3526.xml new file mode 100644 index 000000000..54fed705a --- /dev/null +++ b/doc/src/reference.RFC.3526.xml @@ -0,0 +1,32 @@ +<?xml version='1.0'?> +<!DOCTYPE reference SYSTEM 'rfc2629.dtd'> + +<reference anchor='RFC3526'> + +<front> +<title abbrev='MODPGROUPS'>More MODP Diffie-Hellman groups for IKE</title> +<author initials='T.' surname='Kivinen' fullname='Tero Kivinen'> +<organization>SSH Communications Security</organization> +<address> +<postal> +<street>Fredrikinkatu 42</street> +<street>FIN-00100 HELSINKI</street> +<country>Finland</country></postal> +<email>kivinen@ssh.fi</email></address></author> + +<author initials='M.' surname='Kojo' fullname='Mika Kojo'> +<organization>University of Helsinki</organization> +<address> +<postal> +<street>HELSINKI</street> +<country>Finland</country></postal> +<email>mrskojo@cc.helsinki.fi</email></address></author> + +<date month='March' year='2003'></date> +<area>Security</area> +<keyword>IP security protocol</keyword> +<keyword>IPSEC</keyword> +<keyword>security</keyword></front> + +<seriesInfo name='RFC' value='3526' /> +</reference> diff --git a/doc/src/responderstate.txt b/doc/src/responderstate.txt new file mode 100644 index 000000000..f64b82983 --- /dev/null +++ b/doc/src/responderstate.txt @@ -0,0 +1,43 @@ + | + | IKE main mode + | phase 1 + V + .-----------------. + | unauthenticated | + | OE peer | + `-----------------' + | + | lookup KEY RR in in-addr.arpa + | (if ID_IPV4_ADDR) + | lookup KEY RR in forward + | (if ID_FQDN) + V + .-----------------. RR not found + | received DNS |---------------> log failure + | reply | + `----+--------+---' + phase 2 | \ misformatted + proposal | `------------------> log failure + V + .----------------. + | authenticated | identical initiator + | OE peer |--------------------> initiator + `----------------' connection found state machine + | + | look for TXT record for initiator + | + V + .---------------. + | authorized |---------------------> log failure + | OE peer | + `---------------' + | + | + V + potential OE + connection in + initiator state + machine + + +$Id: responderstate.txt,v 1.1 2004/03/15 20:35:24 as Exp $ diff --git a/doc/src/rfc.html b/doc/src/rfc.html new file mode 100644 index 000000000..762c66c6e --- /dev/null +++ b/doc/src/rfc.html @@ -0,0 +1,158 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>IPsec RFCs</title> + <meta name="keywords" + content="IPsec, VPN, security, FreeSWAN, RFC, standard"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: rfc.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="RFC">IPsec RFCs and related documents</a></h1> + +<h2><a name="RFCfile">The RFCs.tar.gz Distribution File</a></h2> + +<p>The Linux FreeS/WAN distribution is available from <a +href="http://www.xs4all.nl/~freeswan"> our primary distribution site</a> and +various mirror sites. To give people more control over their downloads, the +RFCs that define IP security are bundled separately in the file +RFCs.tar.gz.</p> + +<p>The file you are reading is included in the main distribution and is +available on the web site. It describes the RFCs included in the <a +href="#RFCs.tar.gz">RFCs.tar.gz</a> bundle and gives some pointers to <a +href="#sources">other ways to get them</a>.</p> + +<h2><a name="sources">Other sources for RFCs & Internet drafts</a></h2> + +<h3><a name="RFCdown">RFCs</a></h3> + +<p>RFCs are downloadble at many places around the net such as:</p> +<ul> + <li><a href="http://www.rfc-editor.org">http://www.rfc-editor.org</a></li> + <li><a href="http://nis.nsf.net/internet/documents/rfc">NSF.net</a></li> + <li><a href="http://sunsite.doc.ic.ac.uk/computing/internet/rfc">Sunsite in + the UK</a></li> +</ul> + +<p>browsable in HTML form at others such as:</p> +<ul> + <li><a + href="http://www.landfield.com/rfcs/index.html">landfield.com</a></li> + <li><a href="http://www.library.ucg.ie/Connected/RFC">Connected Internet + Encyclopedia</a></li> +</ul> + +<p>and some of them are available in translation:</p> +<ul> + <li><a href="http://www.eisti.fr/eistiweb/docs/normes/">French</a></li> +</ul> + +<p>There is also a published <a href="biblio.html#RFCs">Big Book of IPSEC +RFCs</a>.</p> + +<h3><a name="drafts">Internet Drafts</a></h3> + +<p>Internet Drafts, working documents which sometimes evolve into RFCs, are +also available.</p> +<ul> + <li><a href="http://www.ietf.org/ID.html">Overall reference page</a></li> + <li><a href="http://www.ietf.org/ids.by.wg/ipsec.html">IPsec</a> working + group</li> + <li><a href="http://www.ietf.org/ids.by.wg/ipsra.html">IPSRA (IPsec Remote + Access)</a> working group</li> + <li><a href="http://www.ietf.org/ids.by.wg/ipsp.html">IPsec Policy</a> + working group</li> + <li><a href="http://www.ietf.org/ids.by.wg/kink.html">KINK (Kerberized + Internet Negotiation of Keys)</a> working group</li> +</ul> + +<p>Note: some of these may be obsolete, replaced by later drafts or by +RFCs.</p> + +<h3><a name="FIPS1">FIPS standards</a></h3> + +<p>Some things used by <a href="glossary.html#IPSEC">IPsec</a>, such as <a +href="glossary.html#DES">DES</a> and <a href="glossary.html#SHA">SHA</a>, are +defined by US government standards called <a +href="glossary.html#FIPS">FIPS</a>. The issuing organisation, <a +href="glossary.html#NIST">NIST</a>, have a <a +href="http://www.itl.nist.gov/div897/pubs">FIPS home page</a>.</p> + +<h2><a name="RFCs.tar.gz">What's in the RFCs.tar.gz bundle?</a></h2> + +<p>All filenames are of the form rfc*.txt, with the * replaced with the RFC +number.</p> +<pre>RFC# Title</pre> + +<h3><a name="rfc.ov">Overview RFCs</a></h3> +<pre>2401 Security Architecture for the Internet Protocol +2411 IP Security Document Roadmap</pre> + +<h3><a name="basic.prot">Basic protocols</a></h3> +<pre>2402 IP Authentication Header +2406 IP Encapsulating Security Payload (ESP)</pre> + +<h3><a name="key.ike">Key management</a></h3> +<pre>2367 PF_KEY Key Management API, Version 2 +2407 The Internet IP Security Domain of Interpretation for ISAKMP +2408 Internet Security Association and Key Management Protocol (ISAKMP) +2409 The Internet Key Exchange (IKE) +2412 The OAKLEY Key Determination Protocol +2528 Internet X.509 Public Key Infrastructure</pre> + +<h3><a name="rfc.detail">Details of various things used</a></h3> +<pre>2085 HMAC-MD5 IP Authentication with Replay Prevention +2104 HMAC: Keyed-Hashing for Message Authentication +2202 Test Cases for HMAC-MD5 and HMAC-SHA-1 +2207 RSVP Extensions for IPSEC Data Flows +2403 The Use of HMAC-MD5-96 within ESP and AH +2404 The Use of HMAC-SHA-1-96 within ESP and AH +2405 The ESP DES-CBC Cipher Algorithm With Explicit IV +2410 The NULL Encryption Algorithm and Its Use With IPsec +2451 The ESP CBC-Mode Cipher Algorithms +2521 ICMP Security Failures Messages</pre> + +<h3><a name="rfc.ref">Older RFCs which may be referenced</a></h3> +<pre>1321 The MD5 Message-Digest Algorithm +1828 IP Authentication using Keyed MD5 +1829 The ESP DES-CBC Transform +1851 The ESP Triple DES Transform +1852 IP Authentication using Keyed SHA</pre> + +<h3><a name="rfc.dns">RFCs for secure DNS service, which IPsec may +use</a></h3> +<pre>2137 Secure Domain Name System Dynamic Update +2230 Key Exchange Delegation Record for the DNS +2535 Domain Name System Security Extensions +2536 DSA KEYs and SIGs in the Domain Name System (DNS) +2537 RSA/MD5 KEYs and SIGs in the Domain Name System (DNS) +2538 Storing Certificates in the Domain Name System (DNS) +2539 Storage of Diffie-Hellman Keys in the Domain Name System (DNS)</pre> + +<h3><a name="rfc.exp">RFCs labelled "experimental"</a></h3> +<pre>2521 ICMP Security Failures Messages +2522 Photuris: Session-Key Management Protocol +2523 Photuris: Extended Schemes and Attributes</pre> + +<h3><a name="rfc.rel">Related RFCs</a></h3> +<pre>1750 Randomness Recommendations for Security +1918 Address Allocation for Private Internets +1984 IAB and IESG Statement on Cryptographic Technology and the Internet +2144 The CAST-128 Encryption Algorithm</pre> +</body> +</html> diff --git a/doc/src/roadmap.html b/doc/src/roadmap.html new file mode 100644 index 000000000..c9d85047c --- /dev/null +++ b/doc/src/roadmap.html @@ -0,0 +1,203 @@ +<html> +<head> +<title>FreeS/WAN roadmap</title> +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN"> + +<!-- + +Written by Sandy Harris for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +CVS information: +RCS ID: $Id: roadmap.html,v 1.1 2004/03/15 20:35:24 as Exp $ +Last changed: $Date: 2004/03/15 20:35:24 $ +Revision number: $Revision: 1.1 $ + +CVS revision numbers do not correspond to FreeS/WAN release numbers. +--> +</head> + +<body> +<h1><a name="roadmap">Distribution Roadmap: What's Where in Linux FreeS/WAN</a></h1> + +<p> +This file is a guide to the locations of files within the FreeS/WAN +distribution. Everything described here should be on your system once you +download, gunzip, and untar the distribution.</p> + +<p>This distribution contains two major subsystems +</p> +<dl> + <dt><a href="#klips.roadmap">KLIPS</a></dt> + <dd>the kernel code</dd> + <dt><a href="#pluto.roadmap">Pluto</a></dt> + <dd>the user-level key-management daemon</dd> +</dl> + +<p>plus assorted odds and ends. +</p> +<h2><a name="top">Top directory</a></h2> + +<p>The top directory has essential information in text files:</p> + +<dl> + <dt>README</dt> + <dd>introduction to the software</dd> + <dt>INSTALL</dt> + <dd>short experts-only installation procedures. More detalied procedures are in + <a href="install.html">installation</a> and + <a href="config.html">configuration</a> HTML documents.</dd> + <dt>BUGS</dt> + <dd>major known bugs in the current release.</dd> + <dt>CHANGES</dt> + <dd>changes from previous releases</dd> + <dt>CREDITS</dt> + <dd>acknowledgement of contributors</dd> + <dt>COPYING</dt> + <dd>licensing and distribution information</dd> +</dl> + +<h2><a name="doc">Documentation</a></h2> + +<p> +The doc directory contains the bulk of the documentation, most of it in +HTML format. See the <a href="index.html">index file</a> for details. +</p> + +<h2><a name="klips.roadmap">KLIPS: kernel IP security</a></h2> +</a> +<p> +<a href="glossary.html#KLIPS">KLIPS</a> is <strong>K</strong>erne<strong>L</strong> +<strong>IP</strong> <strong>S</strong>ecurity. It lives in the klips +directory, of course. +</p> +<dl> + <dt>klips/doc</dt> + <dd>documentation</dd> + <dt>klips/patches</dt> + <dd>patches for existing kernel files</dd> + <dt>klips/test</dt> + <dd>test stuff</dd> + <dt>klips/utils</dt> + <dd>low-level user utilities</dd> + <dt>klips/net/ipsec</dt> + <dd>actual klips kernel files</dd> + <dt>klips/src</dt> + <dd>symbolic link to klips/net/ipsec + <p>The "make insert" step of installation installs the patches and makes + a symbolic link from the kernel tree to klips/net/ipsec. The odd name of + klips/net/ipsec is dictated by some annoying limitations of the scripts + which build the Linux kernel. The symbolic-link business is a bit + messy, but all the alternatives are worse.</p> + <p></p> + </dd> + <dt>klips/utils</dt> + <dd>Utility programs: + <p></p> + <dl> + <dt>eroute</dt> + <dd>manipulate IPsec extended routing tables</dd> + <dt>klipsdebug</dt> + <dd>set Klips (kernel IPsec support) debug features and level</dd> + <dt>spi</dt> + <dd>manage IPsec Security Associations</dd> + <dt>spigrp</dt> + <dd>group/ungroup IPsec Security Associations</dd> + <dt>tncfg</dt> + <dd>associate IPsec virtual interface with real interface</dd> + </dl> + <p>These are all normally invoked by ipsec(8) with commands such as</p> + <pre> ipsec tncfg <var>arguments</var></pre> + There are section 8 man pages for all of these; the names have "ipsec_" + as a prefix, so your man command should be something like: + <pre> man 8 ipsec_tncfg</pre> + </dd> +</dl> + +<h2><a name="pluto.roadmap">Pluto key and connection management daemon</a></h2> + +<p> +<a href="glossary.html#Pluto">Pluto</a> is our key management and negotiation daemon. It +lives in the pluto directory, along with its low-level user utility, +whack. +</p> +<p> +There are no subdirectories. Documentation is a man page, +<a href="manpage.d/ipsec_pluto.8.html">pluto.8</a>. This covers whack as well. +</p> + +<h2><a name="utils">Utils</a></h2> + +<p> +The utils directory contains a growing collection of higher-level user +utilities, the commands that administer and control the software. Most of the +things that you will actually have to run yourself are in there. +</p> +<dl> + <dt>ipsec</dt> + <dd>invoke IPsec utilities + <p>ipsec(8) is normally the only program installed in a standard + directory, /usr/local/sbin. It is used to invoke the others, both those + listed below and the ones in klips/utils mentioned above.</p> + <p></p> + </dd> + <dt>auto</dt> + <dd>control automatically-keyed IPsec connections</dd> + <dt>manual</dt> + <dd>take manually-keyed IPsec connections up and down</dd> + <dt>barf</dt> + <dd>generate copious debugging output</dd> + <dt>look</dt> + <dd>generate moderate amounts of debugging output</dd> +</dl> +<p> +There are .8 manual pages for these. look is covered in barf.8. The man pages +have an "ipsec_" prefix so your man command should be something like: +<pre> + man 8 ipsec_auto +</pre> +<p> +Examples are in various files with names utils/*.eg</p> + +<h2><a name="lib">Libraries</a></h2> + +<h3><a name="fswanlib">FreeS/WAN Library</a></h3> + +<p> +The lib directory is the FreeS/WAN library, also steadily growing, used by +both user-level and kernel code.<br /> +It includes section 3 <a href="manpages.html">man pages</a> for the library routines. +</p> +<h3><a name="otherlib">Imported Libraries</a></h3> + +<h4>LibDES</h4> + +The libdes library, originally from SSLeay, is used by both Klips and Pluto +for <a href="glossary.html#3DES">Triple DES</a> encryption. Single DES is not +used because <a href="politics.html#desnotsecure">it is +insecure</a>. +<p> +Note that this library has its own license, different from the +<a href="glossary.html#GPL">GPL</a> used for other code in FreeS/WAN. + </p> +<p> +The library includes its own documentation. + + +<h4>GMP</h4> + +The GMP (GNU multi-precision) library is used for multi-precision arithmetic +in Pluto's key-exchange code and public key code. +<p> +Older versions (up to 1.7) of FreeS/WAN included a copy of this library in +the FreeS/WAN distribution. +<p> +Since 1.8, we have begun to rely on the system copy of GMP. +</p> + +</body> +</html> + diff --git a/doc/src/testing.html b/doc/src/testing.html new file mode 100644 index 000000000..8ffcca604 --- /dev/null +++ b/doc/src/testing.html @@ -0,0 +1,395 @@ +<html> +<head> +<title>Testing FreeS/WAN</title> + +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, testing"> + +<!-- + +Written by Sandy Harris for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +CVS information: +RCS ID: $Id: testing.html,v 1.1 2004/03/15 20:35:24 as Exp $ +Last changed: $Date: 2004/03/15 20:35:24 $ +Revision number: $Revision: 1.1 $ + +CVS revision numbers do not correspond to FreeS/WAN release numbers. +--> +</head> + +<body> +<h1><a name="test.freeswan">Testing FreeS/WAN</a></h1> +This document discusses testing FreeS/WAN. + +<p>Not all types of testing are described here. Other parts of the +documentation describe some tests:</p> +<dl> + <dt><a href="install.html#testinstall">installation</a> document</dt> + <dd>testing for a successful install</dd> + <dt><a href="config.html#testsetup">configuration</a> document</dt> + <dd>basic tests for a working configuration</dd> + <dt><a href="web.html#interop.web">web links</a> document</dt> + <dd>General information on tests for interoperability between various + IPsec implementations. This includes links to several test sites.</dd> + <dt><a href="interop.html">interoperation</a> document.</dt> + <dd>More specific information on FreeS/WAN interoperation with other + implementations.</dd> + <dt><a href="performance.html">performance</a> document</dt> + <dd>performance measurements</dd> +</dl> + +<p>The test setups and procedures described here can also be used in other +testing, but this document focuses on testing the IPsec functionality of +FreeS/WAN.</p> + +<H2><A NAME="test.oe">Testing opportunistic connections</A></H2> + +<P>This section teaches you how to test your opportunistically encrypted (OE) +connections. To set up OE, please see the easy instructions in our +<A HREF="quickstart.html">quickstart guide</A>.</P> + +<H3>Basic OE Test</H3> + + +<P>This test is for basic OE functionality. +<!-- You may use it on an +<A HREF="quickstart.html#oppo.client">initiate-only OE</A> box or a +<A HREF="quickstart.html#opp.incoming">full OE</A> box. --> +For additional tests, keep reading.</P> + +<P>Be sure IPsec is running. You can see whether it is with:</P> +<PRE> ipsec setup status</PRE> +<P>If need be, you can restart it with:</P> +<PRE> service ipsec restart</PRE> + +<P>Load a FreeS/WAN test website from the host on which you're running +FreeS/WAN. Note: the feds may be watching these sites. Type one of:<P> +<PRE> links oetest.freeswan.org</PRE> +<PRE> links oetest.freeswan.nl</PRE> +<!--<PRE> links oetest.freeswan.ca</PRE>--> + +<P>A positive result looks like this:</P> + +<PRE> + You seem to be connecting from: 192.0.2.11 which DNS says is: + gateway.example.com + _________________________________________________________________ + + Status E-route + OE enabled 16 192.139.46.73/32 -> 192.0.2.11/32 => + tun0x2097@192.0.2.11 + OE enabled 176 192.139.46.77/32 -> 192.0.2.11/32 => + tun0x208a@192.0.2.11 +</PRE> + +<P>If you see this, congratulations! Your OE box will now encrypt +its own traffic whenever it can. If you have difficulty, +see our <A HREF="#oe.trouble">OE troubleshooting tips</A>. +</P> + +<H3>OE Gateway Test</H3> +<P>If you've set up FreeS/WAN to protect a subnet behind your gateway, +you'll need to run another simple test, which can be done from a machine +running any OS. That's right, your Windows box can be protected by +opportunistic encryption without any FreeS/WAN install or configuration +on that box. From <STRONG>each protected subnet node</STRONG>, +load the FreeS/WAN website with:</P> + +<PRE> links oetest.freeswan.org</PRE> +<PRE> links oetest.freeswan.nl</PRE> + +<P>A positive result looks like this:</P> +<PRE> + You seem to be connecting from: 192.0.2.98 which DNS says is: + box98.example.com + _________________________________________________________________ + + Status E-route + OE enabled 16 192.139.46.73/32 -> 192.0.2.98/32 => + tun0x134ed@192.0.2.11 + OE enabled 176 192.139.46.77/32 -> 192.0.2.11/32 => + tun0x134d2@192.0.2.11 +</PRE> + +<P>If you see this, congratulations! Your OE gateway will now encrypt +traffic for this subnet node whenever it can. If you have difficulty, see our +<A HREF="#oe.trouble">OE troubleshooting tips</A>. +</P> + + +<H3>Additional OE tests</H3> + +<P>When testing OE, you will often find it useful to execute this command +on the FreeS/WAN host:</P> +<PRE> ipsec eroute</PRE> + +<P>If you have established a connection (either for or for a subnet node) +you will see a result like:</P> + +<PRE> 192.0.2.11/32 -> 192.139.46.73/32 => tun0x149f@192.139.46.38 +</PRE> + +<P>Key:</P> +<TABLE> +<TR><TD>1.</TD> + <TD>192.0.2.11/32</TD> + <TD>Local start point of the protected traffic. + </TD></TR> +<TR><TD>2.</TD> + <TD>192.0.2.194/32</TD> + <TD>Remote end point of the protected traffic. + </TD></TR> +<TR><TD>3.</TD> + <TD>192.0.48.38</TD> + <TD>Remote FreeS/WAN node (gateway or host). + May be the same as (2). + </TD></TR> +<TR><TD>4.</TD> + <TD>[not shown]</TD> + <TD>Local FreeS/WAN node (gateway or host), where you've produced the output. + May be the same as (1). + </TD></TR> +</TABLE> + + +<P>For extra assurance, you may wish to use a packet sniffer such as +<A HREF="http://www.tcpdump.org">tcpdump</A> to verify that packets +are being encrypted. You should see output that indicates +<STRONG>ESP</STRONG> encrypted data, + for example:</P> + +<PRE> 02:17:47.353750 PPPoE [ses 0x1e12] IP 154: xy.example.com > oetest.freeswan.org: ESP(spi=0x87150d16,seq=0x55)</PRE> + + + +<h2><a name="test.uml">Testing with User Mode Linux</a></h2> + +<p><a href="http://user-mode-linux.sourceforge.net/">User Mode Linux</a> +allows you to run Linux as a user process on another Linux machine.</p> + +<p>As of 1.92, the distribution has a new directory named testing. It +contains a collection of test scripts and sample configurations. Using these, +you can bring up several copies of Linux in user mode and have them build +tunnels to each other. This lets you do some testing of a FreeS/WAN +configuration on a single machine.</p> + +<p>You need a moderately well-endowed machine for this to work well. Each UML +wants about 16 megs of memory by default, which is plenty for FreeS/WAN +usage. Typical regression testing only occasionally uses as many as 4 UMLs. +If one is doing nothing else with the machine (in particular, not running X +on it), then 128 megs and a 500MHz CPU are fine.</p> + +Documentation on these +scripts is <a href="umltesting.html">here</a>. There is also documentation +on automated testing <A href="makecheck.html">here</a>. + +<h2><a name="testnet">Configuration for a testbed network</a></h2> + +<p>A common test setup is to put a machine with dual Ethernet cards in +between two gateways under test. You need at least five machines; two +gateways, two clients and a testing machine in the middle.</p> + +<p>The central machine both routes packets and provides a place to run +diagnostic software for checking IPsec packets. See next section for +discussion of <a href="#tcpdump.faq">using tcpdump(8)</a> for this.</p> + +<p>This makes things more complicated than if you just connected the two +gateway machines directly to each other, but it also makes your test setup +much more like the environment you actually use IPsec in. Those environments +nearly always involve routing, and quite a few apparent IPsec failures turn +out to be problems with routing or with firewalls dropping packets. This +approach lets you deal with those problems on your test setup.</p> + +<p>What you end up with looks like:</p> + +<h3><a name="testbed">Testbed network</a></h3> +<pre> subnet a.b.c.0/24 + | + eth1 = a.b.c.1 + gate1 + eth0 = 192.168.p.1 + | + | + eth0 = 192.168.p.2 + route/monitor box + eth1 = 192.168.q.2 + | + | + eth0 = 192.168.q.1 + gate2 + eth1 = x.y.z.1 + | + subnet x.y.z.0/24</pre> +<pre>Where p and q are any convenient values that do not interfere with other +routes you may have. The ipsec.conf(5) file then has, among other things:</pre> +<pre>conn abc-xyz + left=192.168.p.1 + leftnexthop=192.168.p.2 + right=192.168.q.1 + rightnexthop=192.168.q.2</pre> + +<p>Once that works, you can remove the "route/monitor box", and connect the +two gateways to the Internet. The only parameters in ipsec.conf(5) that need +to change are the four shown above. You replace them with values appropriate +for your Internet connection, and change the eth0 IP addresses and the +default routes on both gateways.</p> + +<p>Note that nothing on either subnet needs to change. This lets you test +most of your IPsec setup before connecting to the insecure Internet.</p> + +<h3><a name="tcpdump.test">Using packet sniffers in testing</a></h3> + +<p>A number of tools are available for looking at packets. We will discuss +using <a href="http://www.tcpdump.org/">tcpdump(8)</a>, a common Linux tool +included in most distributions. Alternatives offerring more-or-less the same +functionality include:</p> +<dl> + <dt><a href="http://www.ethereal.com">Ethereal</a></dt> + <dd>Several people on our mailing list report a preference for this over + tcpdump.</dd> + <dt><a href="http://netgroup-serv.polito.it/windump/">windump</a></dt> + <dd>a Windows version of tcpdump(8), possibly handy if you have Windows + boxes in your network</dd> + <dt><a + href="http://reptile.rug.ac.be/~coder/sniffit/sniffit.html">Sniffit</a></dt> + <dd>A linux sniffer that we don't know much about. If you use it, please + comment on our mailing list.</dd> +</dl> + +<p>See also this <a +href="http://www.tlsecurity.net/unix/ids/sniffer/">index</a> of packet +sniffers.</p> + +<p>tcpdump(8) may misbehave if run on the gateways themselves. It is designed +to look into a normal IP stack and may become confused if you ask it to +display data from a stack which has IPsec in play.</p> + +<p>At one point, the problem was quite severe. Recent versions of tcpdump, +however, understand IPsec well enough to be usable on a gateway. You can get +the latest version from <a href="http://www.tcpdump.org/">tcpdump.org</a>.</p> + +<p>Even with a recent tcpdump, some care is required. Here is part of a post +from Henry on the topic:</p> +<pre>> a) data from sunset to sunrise or the other way is not being +> encrypted (I am using tcpdump (ver. 3.4) -x/ping -p to check +> packages) + +What *interface* is tcpdump being applied to? Use the -i option to +control this. It matters! If tcpdump is looking at the ipsecN +interfaces, e.g. ipsec0, then it is seeing the packets before they are +encrypted or after they are decrypted, so of course they don't look +encrypted. You want to have tcpdump looking at the actual hardware +interfaces, e.g. eth0. + +Actually, the only way to be *sure* what you are sending on the wire is to +have a separate machine eavesdropping on the traffic. Nothing you can do +on the machines actually running IPsec is 100% guaranteed reliable in this +area (although tcpdump is a lot better now than it used to be).</pre> + +<p>The most certain way to examine IPsec packets is to look at them on the +wire. For security, you need to be certain, so we recommend doing that. To do +so, you need a <strong>separate sniffer machine located between the two +gateways</strong>. This machine can be routing IPsec packets, but it must not +be an IPsec gateway. Network configuration for such testing is discussed <a +href="#testnet">above</a>.</p> + +<p>Here's another mailing list message with advice on using tcpdump(8):</p> +<pre>Subject: RE: [Users] Encrypted??? + Date: Thu, 29 Nov 2001 + From: "Joe Patterson" <jpatterson@asgardgroup.com> + +tcpdump -nl -i $EXT-IF proto 50 + +-nl tells it not to buffer output or resolve names (if you don't do that it +may confuse you by not outputing anything for a while), -i $EXT-IF (replace +with your external interface) tells it what interface to listen on, and +proto 50 is ESP. Use "proto 51" if for some odd reason you're using AH, and +"udp port 500" if you want to see the isakmp key exchange/tunnel setup +packets. + +You can also run `tcpdump -nl -i ipsec0` to see what traffic is on that +virtual interface. Anything you see there *should* be either encrypted or +dropped (unless you've turned on some strange options in your ipsec.conf +file) + +Another very handy thing is ethereal (http://www.ethereal.com/) which runs +on just about anything, has a nice gui interface (or a nice text-based +interface), and does a great job of protocol breakdown. For ESP and AH +it'll basically just tell you that there's a packet of that protocol, and +what the spi is, but for isakmp it'll actually show you a lot of the tunnel +setup information (until it gets to the point in the protocol where isakmp +is encrypted....)</pre> + +<h2><a name="verify.crypt">Verifying encryption</a></h2> + +<p>The question of how to verify that messages are actually encrypted has +been extensively discussed on the mailing list. See this <a +href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/07/msg00262.html">thread</a>.</p> + +<p>If you just want to verify that packets are encrypted, look at them with a +packet sniffer (see <a href="#tcpdump.test">previous section</a>) located +between the gateways. The packets should, except for some of the header +information, be utterly unintelligible. <strong>The output of good encryption +looks <em>exactly</em> like random noise</strong>. </p> + +<p>A packet sniffer can only tell you that the data you looked at was +encrypted. If you have stronger requirements -- for example if your security +policy requires verification that plaintext is not leaked during startup or +under various anomolous conditions -- then you will need to devise much more +thorough tests. If you do that, please post any results or methodological +details which your security policy allows you to make public.</p> + +<p>You can put recognizable data into ping packets with something like:</p> +<pre> ping -p feedfacedeadbeef 11.0.1.1</pre> + +<p>"feedfacedeadbeef" is a legal hexadecimal pattern that is easy to pick out +of hex dumps.</p> + +<p>For other protocols, you may need to check if you have encrypted data or +ASCII text. Encrypted data has approximately equal frequencies for all 256 +possible characters. ASCII text has most characters in the printable range +0x20-0x7f, a few control characters less than 0x20, and none at all in the +range 0x80-0xff. 0x20, space, is a good character to look for. In normal +English text space occurs about once in seven characters, versus about once +in 256 for random or encrypted data.</p> + +<p>One thing to watch for: the output of good compression, like that of good +encryption, looks just like random noise. You cannot tell just by looking at +a data stream whether it has been compressed, encrypted, or both. You need a +little care not to mistake compressed data for encrypted data in your +testing.</p> + +<p>Note also that weak encryption also produces random-looking output. You +cannot tell whether the encryption is strong by looking at the output. To be +sure of that, you would need to have both the algorithms and the +implementation examined by experts. </p> + +<p>For IPsec, you can get partial assurance from interoperability tests. See +our <a href="interop.html">interop</a> document. When twenty products all +claim to implement <a href="glossary.html#3DES">3DES</a>, and they all talk +to each other, you can be fairly sure they have it right. Of course, you +might wonder whether all the implementers are consipring to trick you or, +more plausibly, whether some implementations might have "back doors" so they +can get also it wrong when required.. If you're seriously worried about +things like that, you need to get the code you use audited (good luck if it +is not Open Source), or perhaps to talk to a psychiatrist about treatments +for paranoia. </p> + +<h2><a name="mail.test">Mailing list pointers</a></h2> + +<p>Additional information on testing can be found in these <a +href="mail.html">mailing list</a> messages:</p> +<ul> + <li>a user's detailed <a + href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00571.html">setup + diary</a> for his testbed network</li> + <li>a FreeS/WAN team member's <a + href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00425.html">notes</a> + from testing at an IPsec interop "bakeoff"</li> +</ul> +</body> +</html> diff --git a/doc/src/testingtools.html b/doc/src/testingtools.html new file mode 100644 index 000000000..491b1956c --- /dev/null +++ b/doc/src/testingtools.html @@ -0,0 +1,188 @@ +<html> +<head> +<title>FreeS/WAN survey of testing tools</title> +<!-- Changed by: Michael Richardson, 02-Jan-2002 --> +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, testing, nettools"> + +<!-- + +Written by Michael Richardson for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +$Id: testingtools.html,v 1.1 2004/03/15 20:35:24 as Exp $ + +$Log: testingtools.html,v $ +Revision 1.1 2004/03/15 20:35:24 as +added files from freeswan-2.04-x509-1.5.3 + +Revision 1.1 2002/03/12 20:57:25 mcr + review of tools used for testing FreeSWAN systems. + + +--> +</head> + +<body> + +<h1>Survey of testing tools</h1> + +<h2><A HREF="http://freshmeat.net/projects/apsend">http://freshmeat.net/projects/apsend</A></h2> + +<P> +About: <A HREF="">APSEND</A> is a TCP/IP packet sender to test firewalls and other +network applications. It also includes a syn flood option, the land +DoS attack, a DoS attack against tcpdump running on a UNIX-based +system, a UDP-flood attack, and a ping flood option. It currently +supports the following protocols: IP, TCP, UDP, ICMP, Ethernet frames +and you can also build any other type of protocol using the generic +option. The scripting language of apsend is already written, but not +yet public. +</P> + +<P> +STATUS: The public web site seems to have died +</P> + +<h2><A HREF="http://freshmeat.net/projects/hping2">http://freshmeat.net/projects/hping2</A></h2> + +<P> +About: <A HREF="http://www.hping.org/">hping2</A> is a network tool +able to send custom ICMP/UDP/TCP packets and to display target replies +like ping does with ICMP replies. It handles fragmentation and +arbitrary packet body and size, and can be used to transfer files +under supported protocols. Using hping2, you can: test firewall rules, +perform [spoofed] port scanning, test net performance using different +protocols, packet size, TOS (type of service), and fragmentation, do +path MTU discovery, tranfer files (even between really Fascist +firewall rules), perform traceroute-like actions under different +protocols, fingerprint remote OSs, audit a TCP/IP stack, etc. hping2 +is a good tool for learning TCP/IP. +</P> + +<P> +This utility has rather complicated usage and no man page at present. +The documentation is supposed to be in HPING2-HOWTO, but that file +seems to be absent. +</P> + +<h2><A HREF="http://freshmeat.net/projects/icmpush">http://freshmeat.net/projects/icmpush</A></h2> + +<P> +About: ICMPush is a tool that send ICMP packets fully customized from command +line. This release supports the ICMP error types Unreach, Parameter +Problem, Redirect and Source Quench and the ICMP information types +Timestamp, Address Mask Request, Information Request, Router +Solicitation, Router Advertisement and Echo Request. Also supports +ip-spoofing, broadcasting and other useful features. It's really a +powerful program for testing and debugging TCP/IP stacks and networks. +</P> + +<P> +</P> + +<h2><A HREF="http://freshmeat.net/projects/isic">http://freshmeat.net/projects/isic</A></h2> + +<P> +ISIC sends randomly generated packets to a target computer. Its +primary uses are to stress-test an IP stack, to find leaks in a +firewall, and to test the implementation of IDSes and firewalls. The +user can specify how often the packets will be frags, have IP options, +TCP options, an urgent pointer, etc. Programs for TCP, UDP, ICMP, +IP w/ random protocols, and random ethernet frames are included. +</P> + +<h2><A HREF="http://freshmeat.net/projects/sendpacket">http://freshmeat.net/projects/sendpacket</A></h2> + +<P> +Send Packet is a small but powerful program to test how your network +responds to specific packet content. Via a config file and/or command +line parameters, you can forge (modify the headers of) your own +TCP/UDP/ICMP/IP packets and send them through your network. Also, +following the Easy Sniffer modular philosophy, you can specify wich +modules you'd like to build. +</P> + +<h2><A HREF="http://freshmeat.net/projects/aicmpsend/">http://freshmeat.net/projects/aicmpsend/</A></h2> + +<P> +AICMPSEND is an ICMP sender with many features including ICMP +flooding and spoofing. All ICMP flags and codes are implemented. You +can use this program for various DoS attacks, for ICMP flooding and +to test firewalls. +</P> + +<h2><A HREF="http://freshmeat.net/projects/sendip/">http://freshmeat.net/projects/sendip/</A></h2> + +<P> +SendIP is a command-line tool to send arbitrary IP packets. It has a +large number of options to specify the content of every header of a +RIP, TCP, UDP, ICMP, or raw IPv4/IPv6 packet. It also allows any data +to be added to the packet. Checksums can be calculated automatically, +but if you wish to send out wrong checksums, that is supported too. +</P> + +<h2><A HREF="http://laurent.riesterer.free.fr/gasp/index.html">http://laurent.riesterer.free.fr/gasp/index.html</A></h2> + +<P> +GASP stands for 'Generator and Analyzer System for Protocols'. It +allows you to decode and encode any protocols you specify. +</P> + +<P> +The main use is probably to test networks applications : you can +construct packets by hand and test the behavior of your program when +facing some strange packets. But you can image a lot of other +application : e.g. manipulating graphical file or executable +headers. Just describe the specification of the structured data. +</P> + +<P> +GASP is divided in two parts : a compiler which take the specification +of the protocols and generate the code to handle it, this code is a +new Tcl command as GASP in build upon Tcl/Tk and extends the scripting +facilities provided by Tcl. +</P> + +<h2><A HREF="http://pdump.lucidx.com/">http://pdump.lucidx.com/</A></h2> +<h2><A HREF="http://freshmeat.net/projects/aps/">http://freshmeat.net/projects/aps/</A></h2> +<h2><A HREF="http://freshmeat.net/projects/netsed/">http://freshmeat.net/projects/netsed/</A></h2> +<h2><A HREF="http://www.via.ecp.fr/~bbp/netsh/">http://www.via.ecp.fr/~bbp/netsh/</A></h2> +<h2><A HREF="http://www.elxsi.de/">http://www.elxsi.de/</A></h2> +<h2><A HREF="http://www.laurentconstantin.com/us/lcrzo/">http://www.laurentconstantin.com/us/lcrzo/</A></h2> +<h2><A HREF="http://www.joedog.org/libping/index.html">http://www.joedog.org/libping/index.html</A></h2> +<h2><A HREF="http://feynman.mme.wilkes.edu/projects/xNetTools/">http://feynman.mme.wilkes.edu/projects/xNetTools/</A></h2> +<h2><A HREF="http://freshmeat.net/projects/pktsrc/">http://freshmeat.net/projects/pktsrc/</A></h2> +<h2><A HREF="http://freshmeat.net/projects/lcrzoex/">http://freshmeat.net/projects/lcrzoex/</A></h2> +<h2><A HREF="http://freshmeat.net/projects/rain/">http://freshmeat.net/projects/rain/</A></h2> +<P> +rain is a powerful packet builder for testing the stability of +hardware and software. Its features include support for all IP +protocols and the ability to fully customize the packets it sends. +</P> + +<P>(Note, this is not the same as /usr/games/rain)</P> + +<h2><A HREF="http://freshmeat.net/projects/libnet">http://freshmeat.net/projects/libnet</A></h2> +<h2><A HREF="http://freshmeat.net/projects/pftp">http://freshmeat.net/projects/pftp</A></h2> +<h2><A HREF="http://freshmeat.net/projects/pung">http://freshmeat.net/projects/pung</A></h2> + +<P> +pung is a simple server tester. It tries to connect via TCP/IP to a +server but does not transfer any data. It is meant to be used in +scripts that check a list of servers, helping to detect certain common +problems. +</P> + +<h2><A HREF="http://freshmeat.net/projects/thesunpacketshell">http://freshmeat.net/projects/thesunpacketshell</A></h2> +<h2><A HREF="http://freshmeat.net/projects/webperformancetrainer">http://freshmeat.net/projects/webperformancetrainer</A></h2> +<h2><A HREF="http://sourceforge.net/projects/va-ctcs">http://sourceforge.net/projects/va-ctcs</A></h2> +<h2><A HREF="http://synscan.nss.nu/programs.php">http://synscan.nss.nu/programs.php</A></h2> +<h2><A HREF="http://sourceforge.net/projects/va-ctcs">http://sourceforge.net/projects/va-ctcs</A></h2> +<h2><A HREF="http://freshmeat.net/projects/ettercap/">http://freshmeat.net/projects/ettercap/</A></h2> +<h2><A HREF="http://www.dtek.chalmers.se/~d3august/xt/index.html">http://www.dtek.chalmers.se/~d3august/xt/index.html</A></h2> +<h2><A HREF="http://www.opersys.com/LTT/">http://www.opersys.com/LTT/</A></h2> +<h2><A HREF="http://packetstorm.securify.com/DoS/indexdate.shtml">http://packetstorm.securify.com/DoS/indexdate.shtml</A></h2> +<H2> <A HREF="http://comnet.technion.ac.il/~cn1w02/">TCP/IP noise simulator</A></H2> diff --git a/doc/src/trouble.html b/doc/src/trouble.html new file mode 100644 index 000000000..604264c01 --- /dev/null +++ b/doc/src/trouble.html @@ -0,0 +1,840 @@ +<HTML> +<HEAD> + <TITLE>FreeS/WAN troubleshooting</TITLE> + <meta name="keywords" content="Linux, IPSEC, VPN, security, FreeSWAN, troubleshooting, debugging"> +<!-- + Written by Claudia Schmeing for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + +CVS information: +RCS ID: $Id: trouble.html,v 1.1 2004/03/15 20:35:24 as Exp $ +Last changed: $Date: 2004/03/15 20:35:24 $ +Revision number: $Revision: 1.1 $ + +CVS revision numbers do not correspond to FreeS/WAN release numbers. +--> + +</HEAD> +<BODY> + +<H1><A NAME="trouble"></A>Linux FreeS/WAN Troubleshooting Guide</H1> + +<H2><A NAME="overview"></A>Overview</H2> + +<P> +This document covers several general places where you might have a problem:</P> +<OL> + <LI><A HREF="#install">During install</A>.</LI> + <LI><A HREF="#negotiation">During the negotiation process</A>.</LI> + <LI><A HREF="#use">Using an established connection</A>.</LI> +</OL> +<P>This document also contains <A HREF="#notes">notes</A> which +expand on points made in these sections, and tips for +<A HREF="#prob.report">problem +reporting</A>. If the other end of your connection is not FreeS/WAN, +you'll also want to read our +<A HREF="interop.html#interop.problem">interoperation</A> document.</P> +<H2><A NAME="install"></A>1. During Install</H2> +<H3>1.1 RPM install gotchas</H3> +<P>With the RPM method:</P> +<UL> +<LI>Be sure you have installed both the userland tools and the kernel + components. One will not work without the other. For example, when using + FreeS/WAN-produced RPMs for our 2.04 release, you need both: +<PRE> freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm + freeswan-module-2.04_2.4.20_20.9-0.i386.rpm +</PRE> +</LI> +</UL> +<H3>1.2 Problems installing from source</H3> +<P>When installing from source, you may find these problems:</P> +<UL> + <LI>Missing library. See <A HREF="faq.html#gmp.h_missing">this</A> + FAQ.</LI> + <LI>Missing utilities required for compile. See this + <A HREF="install.html#tool.lib">checklist</A>.</LI> + <LI>Kernel version incompatibility. See <A HREF="faq.html#k.versions">this</A> + FAQ.</LI> + <LI>Another compile problem. Find information in the out.* files, + ie. out.kpatch, out.kbuild, created at compile time in the top-level + Linux FreeS/WAN directory. Error messages generated by KLIPS during + the boot sequence are accessible with the <VAR>dmesg</VAR> command. + <BR> + Check the list archives and the List in Brief to see if this is a + known issue. If it is not, report it to the bugs list as described + in our <A HREF="#prob.report">problem reporting</A> section. In some + cases, you may be asked to provide debugging information using gdb; + details <A HREF="#gdb">below</A>.</LI> + <LI>If your kernel compiles but you fail to install your new + FreeS/WAN-enabled kernel, review the sections on <A HREF="install.html#newk">installing + the patched kernel</A>, and <A HREF="install.html#testinstall">testing</A> + to see if install succeeded.</LI> +</UL> +<H3><A NAME="install.check"></A>1.3 Install checks</H3> +<P><VAR>ipsec verify</VAR> checks a number +of FreeS/WAN essentials. Here are some hints on what do to when your +system doesn't check out:</P> +<P> +<TABLE border=1> +<TR> +<TD><STRONG>Problem</STRONG></TD> +<TD><STRONG>Status</STRONG></TD> +<TD><STRONG>Action</STRONG></TD> +</TR> +<TR> +<TD><VAR>ipsec</VAR> not on-path</TD> +<TD> </TD> +<TD><P>Add <VAR>/usr/local/sbin</VAR> to your PATH.</P></TD> +</TR> +<TR> +<TD>Missing KLIPS support</TD> +<TD><FONT COLOR="#FF0000">critical</FONT></TD> +<TD>See <A HREF="faq.html#noKLIPS">this FAQ.</A></TD> +</TR> +<TR> +<TD>No RSA private key</TD> +<TD> </TD> +<TD> +<P>Follow <A HREF="install.html#genrsakey">these +instructions</A> to create an RSA key pair for your host. RSA keys are:</P> +<UL> +<LI>required for opportunistic encryption, and</LI> +<LI>our preferred method to authenticate pre-configured connections.</LI> +</UL> +</TD> +</TR> +<TR> +<TD><VAR>pluto</VAR> not running</TD> +<TD><FONT COLOR="#FF0000">critical</FONT></TD> +<TD><PRE>service ipsec start</PRE></TD> +</TR> +<TR> +<TD>No port 500 hole</TD> +<TD><FONT COLOR="#FF0000">critical</FONT></TD> +<TD>Open port 500 for IKE negotiation.</TD> +</TR> +<TR> +<TD>Port 500 check N/A</TD> +<TD> </TD> +<TD>Check that port 500 is open for IKE negotiation.</TD> +</TR> +<TR> +<TD>Failed DNS checks</TD> +<TD> </TD> +<TD>Opportunistic encryption requires information from DNS. +To set this up, see <A HREF="quickstart.html#opp.setup">our instructions</A>. +</TD> +</TR> +<TR> +<TD>No public IP address</TD> +<TD> </TD> +<TD>Check that the interface which you want to protect with IPSec is up and +running.</TD> +</TR> +</TABLE> + + +<H3><A NAME="oe.trouble"></A>1.3 Troubleshooting OE</H3> +<P>OE should work with no local configuration, if you have posted +DNS TXT records according to the instructions in our +<A HREF="quickstart.html">quickstart guide</A>. +If you encounter trouble, try these hints. +We welcome additional hints via the +<A HREF="mail.html">users' mailing list</A>.</P> + +<TABLE border=1> +<TR> +<TD><STRONG>Symptom</STRONG></TD> +<TD><STRONG>Problem</STRONG></TD> +<TD><STRONG>Action</STRONG></TD> +</TR> +<TR> +<TD> +You're running FreeS/WAN 2.01 (or later), +and initiating a connection to FreeS/WAN +2.00 (or earlier). +In your logs, you see a message like: +<pre>no RSA public key known for '192.0.2.13'; +DNS search for KEY failed (no KEY record +for 13.2.0.192.in-addr.arpa.)</pre> +The older FreeS/WAN logs no error. +</TD> +<TD> +<A NAME="oe.trouble.flagday"></A> +A protocol level incompatibility between 2.01 (or later) and +2.00 (or earlier) causes this error. It occurs when a FreeS/WAN 2.01 +(or later) box for which no KEY record is posted attempts to initiate an OE +connection to older FreeS/WAN versions (2.00 and earlier). +Note that older versions can initiate to newer versions without this error. +</TD> +<TD>If you control the peer host, upgrade its FreeS/WAN to 2.01 (or later), and +post new style TXT records for it. If not, but if you know its sysadmin, +perhaps a quick note is in order. If neither option is possible, you can +ease the transition by posting an old style KEY record (created with a +command like "ipsec showhostkey --key") to the reverse map for +the FreeS/WAN 2.01 (or later) box.</TD> +</TR> +<TR> +<TD>OE host is very slow to contact other hosts.</TD> +<TD>Slow DNS service while running OE.</TD> +<TD>It's a good idea to run a caching DNS server on your OE host, +as outlined in <A HREF="http://lists.freeswan.org/pipermail/design/2003-January/004205.html">this +mailing list message</A>. If your DNS servers are elsewhere, +put their IPs +in the <VAR>clear</VAR> policy group, and +re-read groups with <PRE>ipsec auto --rereadgroups</PRE> +</TD> +</TR> +<TR> +<TD> +<PRE>Can't Opportunistically initiate for +192.0.2.2 to 192.0.2.3: no TXT record +for 13.2.0.192.in-addr.arpa.</PRE> +</TD> +<TD>Peer is not set up for OE.</TD> +<TD><P>None. Plenty of hosts on the Internet +do not run OE. If, however, you have set OE up on that peer, this may +indicate that you need to wait up to 48 hours +for its DNS records to propagate.</P></TD> +</TR> +<TR> +<TD><VAR>ipsec verify</VAR> does not find DNS records: +<PRE>... +Looking for TXT in forward map: + xy.example.com...[FAILED] +Looking for TXT in reverse map...[FAILED] +...</PRE> + +You also experience authentication failure:<BR> +<PRE>Possible authentication failure: +no acceptable response to our +first encrypted message</PRE> +</TD> + +<TD>DNS records are not posted or have not propagated.</TD> +<TD>Did you post the DNS records necessary for OE? If not, +do so using the instructions in our +<A HREF="quickstart.html#quickstart">quickstart guide</A>. +If so, wait up to 48 hours for the DNS records to propagate.</TD> +</TR> +<TR> +<TD><VAR>ipsec verify</VAR> does not find DNS records, and you experience +authentication failure.</TD> +<TD>For iOE, your ID +does not match location of +forward DNS record.</TD> +<TD>In <VAR>config setup</VAR>, change +<VAR>myid=</VAR> to match the forward DNS where you posted the record. +Restart FreeS/WAN. + For reference, see our +<A HREF="quickstart.html#opp.client">iOE instructions</A>.</TD> +</TR> +<TR> +<TD><VAR>ipsec verify</VAR> finds DNS records, yet there is +still authentication failure. ( ? )</TD> +<TD>DNS records are malformed.</TD> +<TD>Re-create the records and send new copies to your DNS administrator.</TD> +</TR> +<TR> +<TD><VAR>ipsec verify</VAR> finds DNS records, yet there is +still authentication failure. ( ? )</TD> +<TD>DNS records show different keys for a gateway vs. its subnet hosts.</TD> +<TD>All TXT records for boxes protected by an OE gateway must contain the +gateway's public key. Re-create and re-post any incorrect records using +<A HREF="quickstart.html#opp.incoming">these instructions</A>.</TD> +</TR> +<TR> +<TD>OE gateway loses connectivity to its subnet. The gateway's +routing table shows routes to the subnet through IPsec interfaces.</TD> +<TD>The subnet is part of the <VAR>private</VAR> or <VAR>block</VAR> +policy group on the gateway.</TD> +<TD>Remove the subnet from the group, and reread +groups with <PRE>ipsec auto --rereadgroups</PRE></TD> +</TR> +<TR> +<TD>OE does not work to hosts on the local LAN.</TD> +<TD>This is a known issue.</TD> +<TD>See <A HREF="opportunism.known-issues">this list</A> of known issues +with OE. +</TD> +</TR> + +<TR> +<TD>FreeS/WAN does not seem to be executing your default policy. In your +logs, you see a message like: +<PRE>/etc/ipsec.d/policies/iprivate-or-clear" +line 14: subnet "0.0.0.0/0", +source 192.0.2.13/32, +already "private-or-clear"</PRE> +</TD> +<TD><A HREF="glossary.html#fullnet">Fullnet</A> in a policy group file defines +your default policy. Fullnet should normally be present in only one policy +group file. The fine print: you can have two default policies defined so long +as they protect different local endpoints (e.g. the FreeS/WAN gateway and a +subnet).</TD> +<TD> +Find all policies which contain fullnet with:<br> +<PRE>grep -F 0.0.0.0/0 /etc/ipsec.d/policies/*</PRE> +then remove the unwanted occurrence(s). +</TD> +</TR> + +</TABLE> + + +<H2><A NAME="negotiation"></A>2. During Negotiation</H2> +<P>When you fail to bring up a tunnel, you'll need to find out:</P> +<UL> +<LI><A HREF="#state">what your connection state is,</A> and often</LI> +<LI><A HREF="#find.pluto.error">an error message</A>.</LI> +</UL> +<P>before you can +<A HREF="#interpret.pluto.error">diagnose your problem</A>.</P> +<H3><A NAME="state"></A>2.1 Determine Connection State</H3> +<H4>Finding current state</H4> +<P>You can see connection states (STATE_MAIN_I1 and so on) when you +bring up a connection on the command line. If you have missed this, +or brought up your connection automatically, use: +</P> +<PRE>ipsec auto --status</PRE> +<P>The most relevant state is the last one reached.</P> +<H4><VAR>What's this supposed to look like?</VAR></H4> +<P>Negotiations should proceed though various states, in the processes of:</P> +<OL> +<LI>IKE negotiations (aka Phase 1, Main Mode, STATE_MAIN_*)</LI> +<LI>IPSEC negotiations (aka Phase 2, Quick Mode, STATE_QUICK_*)</LI> +</OL> +<P>These are done and a connection is established when you see messages like:</P> +<PRE> 000 #21: "myconn" STATE_MAIN_I4 (ISAKMP SA established)... + 000 #2: "myconn" STATE_QUICK_I2 (sent QI2, IPsec SA established)...</PRE><P> +Look for the key phrases are "ISAKMP SA established" and "IPSec +SA established", with the relevant connection name. Often, this happens +at STATE_MAIN_I4 and STATE_QUICK_I2, respectively.</P> +<P><VAR>ipsec auto --status</VAR> will tell you what states <STRONG>have +been achieved</STRONG>, rather than the current state. Since +determining the current state is rather more difficult to do, current +state information is not available from Linux FreeS/WAN. If you are +actively bringing a connection up, the status report's last states +for that connection likely reflect its current state. Beware, though, +of the case where a connection was correctly brought up but is now +downed: Linux FreeS/WAN will not notice this until it attempts to +rekey. Meanwhile, the last known state indicates that the connection +has been established.</P> +<P>If your connection is stuck at STATE_MAIN_I1, skip straight to +<A HREF="#ikepath">here</A>. + +<H3><A NAME="find.pluto.error"></A>2.2 Finding error text</H3> +<P>Solving most errors will require you to find verbose error text, +either on the command line or in the logs.</P> +<H4>Verbose start for more information</H4> +<P> +Note that you can get more detail from <VAR>ipsec auto</VAR> using +the --verbose flag:</P> +<PRE STYLE="margin-bottom: 0.2in"> ipsec auto --verbose --up west-east</PRE><P> +More complete information can be gleaned from the <A HREF="#logusage">log +files</A>.</P> + +<H4>Debug levels count</H4> +<P>The amount of description you'll get here depends on ipsec.conf debug +settings, <VAR>klipsdebug</VAR>= and <VAR>plutodebug</VAR>=. +When troubleshooting, set at least one of these to <VAR>all</VAR>, and +when done, reset it to <VAR>none</VAR> so your logs don't fill up. +Note that you must have enabled the <VAR>klipsdebug</VAR> +<A HREF="install.html#allbut">compile-time option</A> for the +<VAR>klipsdebug</VAR> configuration switch to work.</P> +<P>For negotiation problems <VAR>plutodebug</VAR> is most relevant. +<VAR>klipsdebug</VAR> applies mainly to attempts to use an +already-established connection. See also <A HREF="ipsec.html#parts">this</A> +description of the division of duties within Linux FreeS/WAN.</P> +<P>After raising your debug levels, restart Linux FreeS/WAN to ensure +that ipsec.conf is reread, then recreate the error to generate +verbose logs. +</P> +<H4><VAR>ipsec barf</VAR> for lots of debugging information</H4> +<P> +<A HREF="manpage.d/ipsec_barf.8.html"><VAR>ipsec barf (8)</VAR></A> +collects a bunch of useful debugging information, including these logs +Use the command</P> +<PRE> + ipsec barf > barf.west +</PRE> +<P>to generate one.</P> +<H4>Find the error</H4> +<P>Search out the failure point in your logs. + Are there a handful of lines which succinctly describe how +things are going wrong or contrary to your expectation? Sometimes the +failure point is not immediately obvious: Linux FreeS/WAN's errors +are usually not marked "Error". Have a look in the +<A HREF="faq.html">FAQ</A> +for what some common failures look like.</P> +<P>Tip: problems snowball. +Focus your efforts on the first problem, which is likely to be the +cause of later errors.</P> +<H4>Play both sides</H4> +<P>Also find error text on the peer IPSec box. +This gives you two perspectives on the same failure.</P> +<P>At times you will require information which only one side has. +The peer can merely indicate the presence of an error, and its +approximate point in the negotiations. If one side keeps retrying, +it may be because there is a show stopper on the other side. +Have a look at the other side and figure out what it doesn't like.</P> +<P>If the other end is not Linux FreeS/WAN, the principle is the +same: replicate the error with its most verbose logging on, and +capture the output to a file.</P> +<H3><A NAME="interpret.pluto.error"></A>2.3 Interpreting a Negotiation Error</H3> +<H4><A NAME="ikepath"></A>Connection stuck at STATE_MAIN_I1</H4> +<P>This error commonly happens because IKE (port 500) packets, needed +to negotiate an IPSec connection, cannot travel freely between your IPSec +gateways. See <A HREF="firewall.html#packets">our firewall document</A> +for details.</P> +<H4>Other errors</H4> +<P>Other errors require a bit more digging. Use the following resources:</P> +<UL> + <LI><A HREF="faq.html">the FAQ</A> . Since this document is + constantly updated, the snapshot's FAQ may have a new entry relevant + to your problem.</LI> + <LI>our <A HREF="background.html">background document</A> . + Special considerations which, while not central to Linux FreeS/WAN, + are often tripped over. Includes problems with + <a href="background.html#MTU.trouble">packet fragmentation</a>, + and considerations for + testing opportunism.</LI> + <LI>the <A HREF="mail.html#lists">list archives</A>. Each of the + searchable archives works differently, so it's worth checking each. + Use a search term which is generic, but identifies your error, for + example "No connection is known for". + <BR> + Often, you will find that your question has been answered in the + past. Finding an archived answer is quicker than asking the list. + You may, however, find similar questions without answers. If you do, + send their URLs to the list with your trouble report. The additional + examples may help the list tech support person find your answer.</LI> + <LI>Look into the code where the error is being generated. The + pluto code is nicely documented with comments and meaningful + variable names.</LI> +</UL> +<P>If you have failed to solve your problem with the help of these +resources, send a detailed problem report to the users list, +following these <A HREF="#prob.report">guidelines</A>.</P> +<H2><A NAME="use"></A>3. Using a Connection</H2> +<H3>3.1 Orienting yourself</H3> +<H4><VAR>How do I know if it works?</VAR></H4> +<P>Test your connection by sending packets through it. The simplest way +to do this is with ping, but the ping needs to <STRONG>test the correct +tunnel.</STRONG> See <A HREF="#testgates">this example scenario</A> if +you don't understand this.<P> +<P>If your ping returns, test any other connections you've brought +u all check out, great. You may wish to <A HREF="#bigpacket">test +with large packets</A> for MTU problems.</P> +<H4><VAR>ipsec barf</VAR> is useful again</H4> +<P>If your ping fails to return, generate an ipsec barf debugging +report on each IPSec gateway. On a non-Linux FreeS/WAN +implementation, gather equivalent information. Use this, and the tips +in the next sections, to troubleshoot. Are you sure that both +endpoints are capable of hearing and responding to ping?</P> +<H3>3.2 Those pesky configuration errors</H3> +<P>IPSec may be dropping your ping packets since they do not belong in the +tunnels you have constructed:</P> +<UL> +<LI>Your ping may not test the tunnel you intend to test. For details, see our +<A HREF="faq.html#cantping">"I can't ping"</A> FAQ. +</LI> +<LI> +Alternately, you may have a configuration error. +For example, you may have configured one of the four possible tunnels between +two gateways, but not the one required to secure the important +traffic you're now testing. In this case, add and start the tunnel, +and try again. +</LI> +</UL> +<P>In either case, you will often see a message like:</P> +<PRE>klipsdebug... no eroute</PRE> +<P>which we discuss in <A HREF="faq.html#no_eroute">this +FAQ</A>.</P> +<P>Note:</P> +<UL> +<LI><A HREF="glossary.html#NAT.gloss">Network Address Translation (NAT)</A> +and <A HREF="glossary.html#masq">IP masquerade</A> may have an effect on +which tunnels you need to configure.</LI> +<LI>When testing a tunnel that protects a multi-node subnet, try several +subnet nodes as ping targets, in case one node is routing incorrectly.</LI> +</UL> +<H3><A NAME="route.firewall"></A>3.3 Check Routing and Firewalling</H3> +<P>If you've confirmed your configuration assumptions, the problem is +almost certainly with routing or firewalling. Isolate the problem +using interface statistics, firewall statistics, or a packet sniffer.</P> +<H4>Background:</H4> +<UL> + <LI>Linux FreeS/WAN supplies all the special routing it needs; + you need only route packets out through your IPSec gateway. Verify + that on the <VAR>subnetted</VAR> machines you are using for your + ping-test, your routing is as expected. I have seen a tunnel + "fail" because the subnet machine sending packets + out an alternate gateway (not our IPSec gateway) on their return path. + <LI>Linux FreeS/WAN requires particular <A HREF="firewall.html"> + firewalling considerations</A>. + Check the firewall rules on your IPSec gateways and ensure that they + allow IPSec traffic through. Be sure that no other machine - for + example a router between the gateways - is blocking your IPSec + packets. +</UL> +<H4><A NAME="ifconfig"></A>View Interface and Firewall +Statistics</H4> +<P>Interface reports and firewall statistics can help you track down +lost packets at a glance. Check any firewall statistics you may be keeping +on your IPSec gateways, for dropped packets.</P> + +<P><STRONG>Tip</STRONG>: You can take a snapshot of the packets processed +by your firewall with:</P> + +<PRE> iptables -L -n -v</PRE> + +<P>You can get creative with "diff" to find out what happens to a +particular packet during transmission.</P> + +<P>Both <VAR>cat /proc/net/dev</VAR> and <VAR>ifconfig</VAR> display +interface statistics, and both are included in <VAR>ipsec barf</VAR>. Use +either to check if any interface has dropped packets. If you find +that one has, test whether this is related to your ping. While you +ping continuously, print that interface's statistics several times. +Does its drop count increase in proportion to the ping? If so, check +why the packets are dropped there.</P> + +<P>To do this, look at the firewall rules that apply to that interface. If the +interface is an IPSec interface, more information may be available in +the log. Grep for the word "drop" in a log which was +created with <VAR>klipsdebug=all</VAR> as the error happened.</P> +<P>See also this <A HREF="#ifconfig1">discussion</A> on interpreting +<VAR>ifconfig</VAR> statistics.</P> +<H3><A NAME="sniff"></A>3.4 When in doubt, sniff it out</H3> +<P>If you have checked configuration assumptions, routing, and +firewall rules, and your interface statistics yield no clue, it +remains for you to investigate the mystery of the lost packet by the +most thorough method: with a packet sniffer (providing, of course, +that this is legal where you are working). +<P>In order to detect packets on the ipsec virtual interfaces, +you will need an up-to-date sniffer (tcpdump, ethereal, ksnuffle) on +your IPSec gateway machines. You may also find it useful to sniff the ping +endpoints.</P> +<H4>Anticipate your packets' path</H4> +<P>Ping, and examine each interface along the projected path, checking for your +ping's arrival. If it doesn't get to the the next stop, you have narrowed +down where to look for it. In this way, you can isolate a problem area, +and narrow your troubleshooting focus.</P> +<P>Within a machine running Linux FreeS/WAN, this +<A HREF="firewall.html#packets">packet flow diagram</A> will help you +anticipate a packet's path. +<P>Note that:</P> +<UL> +<LI> +from the perspective of the tunneled packet, the entire tunnel is one hop. +That's explained in <A HREF="faq.html#no_trace">this</A> FAQ. +</LI> +<LI> + an encapsulated IPSec packet will look different, when +sniffed, from the plaintext packet which generated it. You +can see plaintext packets entering an IPSec interface and the +resulting cyphertext packets as they emerge from the corresponding +physical interface. +</LI> +</UL> +<P>Once you isolate where the packet is lost, take a closer look at +firewall rules, routing and configuration assumptions as they affect +that specific area. If the packet is lost on an IPSec gateway, comb +through <VAR>klipsdebug</VAR> output for anomalies. +</P> +<P>If the packet goes through both gateways successfully and reaches +the ping target, but does not return, suspect routing. Check that the +ping target routes packets back to the IPSec gateway.</P> +<H3><A NAME="find.use.error"></A>3.5 Check your logs</H3> +<P>Here, too, log information can be useful. Start with the +<A HREF="#find.pluto.error">guidelines above</A>.</P> +<P>For connection use problems, set <VAR>klipsdebug=all</VAR>. Note +that you must have enabled the <VAR>klipsdebug</VAR> +<A HREF="install.html#allbut">compile-time option</A> to do this. +Restart Linux FreeS/WAN so that it rereads <VAR>ipsec.conf</VAR>, +then recreate the error condition. When searching through +<VAR>klipsdebug</VAR> data, look especially for the keywords +"drop" (as in dropped packets) and "error".</P> +<P>Often the problem with connection use is not software error, but +rather that the software is behaving contrary to expectation. +</P> +<H4><A NAME="interpret.use.error"></A>Interpreting log text</H4> +<P>To interpret the Linux FreeS/WAN log text you've found, use the +same resources as indicated for troubleshooting +connection negotiation: +<A HREF="faq.html">the FAQ</A> , our +<A HREF="background.html">background document</A>, and the +<A HREF="mail.html#lists">list archives</A>. +Looking in the KLIPS code is only for the very brave.</P> +<P>If you are still stuck, send a <A HREF="#prob.report">detailed +problem report</A> to the users' list.</P> +<H3><A NAME="bigpacket"></A>3.6 More testing for the truly thorough</H3> +<H4>Large Packets</H4> +<P>If each of your connections passed the ping test, you may wish to +test by pinging with large packets (2000 bytes or larger). If it does +not return, suspect MTU issues, and see this <A HREF="background.html#MTU.trouble">discussion</A>.</P> +<H4>Stress Tests</H4> +<P>In most users' view, a simple ping test, and perhaps a +large-packet ping test suffice to indicate a working IPSec +connection.</P> +<P>Some people might like to do additional stress tests prior to +production use. They may be interested in this <A HREF="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/12/msg00224.html">testing +protocol</A> we use at interoperation conferences, aka "bakeoffs". +We also have a <VAR>testing</VAR> directory that ships with the +release.</P> +<H2><A NAME="prob.report"></A>4. Problem Reporting</H2> +<H3>4.1 How to ask for help</H3> +<P>Ask for troubleshooting help on the users' mailing list, +<A HREF="mailto:users@lists.freeswan.org">users@lists.freeswan.org</A>. +While sometimes an initial query with a quick description of your +intent and error will twig someone's memory of a similar problem, +it's often necessary to send a second mail with a complete problem +report. +</P> + + +<P>When reporting problems to the mailing list(s), please include: +</P> +<UL> + <LI>a brief description of the problem</LI> + <LI>if it's a compile problem, the actual output from make, + showing the problem. Try to edit it down to only the relevant part, + but when in doubt, be as complete as you can. If it's a kernel + compile problem, any relevant out.* files</LI> + <LI>if it's a run-time problem, pointers to where we can find the + complete output from "ipsec barf" from BOTH ENDS (not just + one of them). Remember that it's common outside the US and Canada to + pay for download volume, so if you can't post barfs on the web and + send the URL to the mailing list, at least compress them with tar or + gzip.<BR> + If you can, try to simplify the case that is causing the problem. + In particular, if you clear your logs, start FreeS/WAN with no other + connections running, cause the problem to happen, and then do <VAR>ipsec + barf</VAR> on both ends immediately, that gives the smallest and + least cluttered output.</LI> + <LI>any other error messages, complaints, etc. that you saw. + Please send the complete text of the messages, not just a summary.</LI> + <LI>what your network setup is. Include subnets, gateway + addresses, etc. A schematic diagram is a + good format for this information.</LI> + <LI>exactly what you were trying to do with Linux FreeS/WAN, and + exactly what went wrong</LI> + <LI>a fix, if you have one. But remember, you are sending mail to + people all over the world; US residents and US citizens in + particular, please read doc/exportlaws.html before sending code -- + even small bug fixes -- to the list or to us.</LI> + <LI>When in doubt about whether to include some seemingly-trivial + item of information, include it. It is rare for problem reports to + have too much information, and common for them to have too little.</LI> +</UL> + +<P>Here are some good general guidelines on bug reporting: +<a href="http://tuxedo.org/~esr/faqs/smart-questions.html">How To Ask Questions +The Smart Way</a> and <a +href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report +Bugs Effectively</a>.</p> + + +<H3>4.2 Where to ask</H3> +<P>To report a problem, send mail about it to the users' list. If you +are certain that you have found a bug, report it to the bugs list. If +you encounter a problem while doing your own coding on the Linux +FreeS/WAN codebase and think it is of interest to the design team, +notify the design list. When in doubt, default to the users' list. +More information about the mailing lists is found <A HREF="mail.html#lists">here</A>.</P> +<P>For a number of reasons -- including export-control regulations +affecting almost any <STRONG>private</STRONG> discussion of +encryption software -- we prefer that problem reports and discussions +go to the lists, not directly to the team. Beware that the list goes +worldwide; US citizens, read this important information about your +<A HREF="politics.html#exlaw">export laws</A>. If you're using this +software, you really should be on the lists. To get onto them, visit +<A HREF="http://lists.freeswan.org/">lists.freeswan.org</A>.</P> +<P>If you do send private mail to our coders or want a private reply +from them, please make sure that the return address on your mail +(From or Reply-To header) is a valid one. They have more important +things to do than to unravel addresses that have been mangled in an +attempt to confuse spammers. +</P> +<H2><A NAME="notes"></A>5. Additional Notes on Troubleshooting</H2> +<P>The following sections supplement the Guide: <A HREF="#system.info">information +available on your system</A>; <A HREF="#testgates">testing between +security gateways</A>; <A HREF="#ifconfig1">ifconfig reports for +KLIPS debugging</A>; <A HREF="#gdb">using GDB on Pluto</A>.</P> +<H3><A NAME="system.info"></A>5.1 Information available on your +system</H3> +<H4><A NAME="logusage"></A>Logs used</H4> +<P>Linux FreeS/WAN logs to:</P> +<UL> + <LI>/var/log/secure (or, on Debian, /var/log/auth.log)</LI> + <LI>/var/log/messages</LI> +</UL> +<P>Check both places to get full information. If you find nothing, +check your <VAR>syslogd.conf(5)</VAR> to see where your +/etc/syslog.conf or equivalent is directing <VAR>authpriv</VAR> +messages.</P> +<H4><A NAME="pages"></A>man pages provided</H4> +<DL> + <DT><A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A> + </DT><DD> + Manual page for IPSEC configuration file. + </DD><DT> + <A HREF="manpage.d/ipsec.8.html">ipsec(8)</A> + </DT><DD STYLE="margin-bottom: 0.2in"> + Primary man page for ipsec utilities. + </DD></DL> +<P> +Other man pages are on <A HREF="manpages.html">this list</A> and in</P> +<UL> + <LI>/usr/local/man/man3</LI> + <LI>/usr/local/man/man5</LI> + <LI>/usr/local/man/man8/ipsec_*</LI> +</UL> +<H4><A NAME="statusinfo"></A>Status information</H4> +<DL> + <DT>ipsec auto --status + </DT><DD> + Command to get status report from running system. Displays Pluto's + state. Includes the list of connections which are currently "added" + to Pluto's internal database; lists state objects reflecting ISAKMP + and IPsec SAs being negotiated or installed. + </DD><DT> + ipsec look + </DT><DD> + Brief status info. + </DD><DT> + ipsec barf + </DT><DD STYLE="margin-bottom: 0.2in"> + Copious debugging info. + </DD></DL> +<H3> +<A NAME="testgates"></A>5.2 Testing between security gateways</H3> +<P>Sometimes you need to test a subnet-subnet tunnel. This is a +tunnel between two security gateways, which protects traffic on +behalf of the subnets behind these gateways. On this network:</P> +<PRE> Sunset==========West------------------East=========Sunrise + IPSec gateway IPSec gateway + local net untrusted net local net</PRE><P> +you might name this tunnel sunset-sunrise. You can test this tunnel +by having a machine behind one gateway ping a machine behind the +other gateway, but this is not always convenient or even possible.</P> +<P>Simply pinging one gateway from the other is not useful. Such a +ping does not normally go through the tunnel. <STRONG>The tunnel +handles traffic between the two protected subnets, not between the +gateways</STRONG> . Depending on the routing in place, a ping might</P> +<UL> + <LI>either succeed by finding an + unencrypted route</LI> + <LI>or fail by finding no route. Packets without an IPSEC eroute + are discarded.</LI> +</UL> +<P><STRONG>Neither event tells you anything about the tunnel</STRONG>. +You can explicitly create an eroute to force such packets through the +tunnel, or you can create additional tunnels as described in our +<A HREF="config.html#multitunnel">configuration document</A>, but +those may be unnecessary complications in your situation.</P> +<P>The trick is to explicitly test between <STRONG>both gateways' +private-side IP addresses</STRONG>. Since the private-side interfaces +are on the protected subnets, the resulting packets do go via the +tunnel. Use either ping -I or traceroute -i, both of which allow you +to specify a source interface. (Note: unsupported on older Linuxes). +The same principles apply for a road warrior (or other) case where +only one end of your tunnel is a subnet.</P> +<H3><A NAME="ifconfig1"></A>5.3 ifconfig reports for KLIPS debugging</H3> +<P>When diagnosing problems using ifconfig statistics, you may wonder +what type of activity increments a particular counter for an ipsecN +device. Here's an index, posted by KLIPS developer Richard Guy +Briggs:</P> +<PRE>Here is a catalogue of the types of errors that can occur for which +statistics are kept when transmitting and receiving packets via klips. +I notice that they are not necessarily logged in the right counter. +. . . + +Sources of ifconfig statistics for ipsec devices + +rx-errors: +- packet handed to ipsec_rcv that is not an ipsec packet. +- ipsec packet with payload length not modulo 4. +- ipsec packet with bad authenticator length. +- incoming packet with no SA. +- replayed packet. +- incoming authentication failed. +- got esp packet with length not modulo 8. + +tx_dropped: +- cannot process ip_options. +- packet ttl expired. +- packet with no eroute. +- eroute with no SA. +- cannot allocate sk_buff. +- cannot allocate kernel memory. +- sk_buff internal error. + + +The standard counters are: + +struct enet_statistics +{ + int rx_packets; /* total packets received */ + int tx_packets; /* total packets transmitted */ + int rx_errors; /* bad packets received */ + int tx_errors; /* packet transmit problems */ + int rx_dropped; /* no space in linux buffers */ + int tx_dropped; /* no space available in linux */ + int multicast; /* multicast packets received */ + int collisions; + + /* detailed rx_errors: */ + int rx_length_errors; + int rx_over_errors; /* receiver ring buff overflow */ + int rx_crc_errors; /* recved pkt with crc error */ + int rx_frame_errors; /* recv'd frame alignment error */ + int rx_fifo_errors; /* recv'r fifo overrun */ + int rx_missed_errors; /* receiver missed packet */ + + /* detailed tx_errors */ + int tx_aborted_errors; + int tx_carrier_errors; + int tx_fifo_errors; + int tx_heartbeat_errors; + int tx_window_errors; +}; + +of which I think only the first 6 are useful.</PRE><H3> +<A NAME="gdb"></A>5.4 Using GDB on Pluto</H3> +<P>You may need to use the GNU debugger, gdb(1), on Pluto. This +should be necessary only in unusual cases, for example if you +encounter a problem which the Pluto developer cannot readily +reproduce or if you are modifying Pluto. +</P> +<P>Here are the Pluto developer's suggestions for doing this: +</P> +<PRE>Can you get a core dump and use gdb to find out what Pluto was doing +when it died? + +To get a core dump, you will have to set dumpdir to point to a +suitable directory (see <A HREF="manpage.d/ipsec.conf.5.html">ipsec.conf(5)</A>). + +To get gdb to tell you interesting stuff: + $ script + $ cd dump-directory-you-chose + $ gdb /usr/local/lib/ipsec/pluto core + (gdb) where + (gdb) quit + $ exit + +The resulting output will have been captured by the script command in +a file called "typescript". Send it to the list. + +Do not delete the core file. I may need to ask you to print out some +more relevant stuff.</PRE><P> +Note that the <VAR>dumpdir</VAR> parameter takes effect only when the +IPsec subsystem is restarted -- reboot or ipsec setup restart.</P> +<P><BR><BR> +</P> +</BODY> +</HTML> diff --git a/doc/src/uml-rhroot-list.txt b/doc/src/uml-rhroot-list.txt new file mode 100644 index 000000000..198997032 --- /dev/null +++ b/doc/src/uml-rhroot-list.txt @@ -0,0 +1,91 @@ +filesystem-2.1.6-2 +glibc-common-2.2.4-13 +slang-1.4.4-4 +newt-0.50.33-1 +mktemp-1.5-11 +syslinux-1.52-2 +which-2.12-3 +zlib-devel-1.1.3-24 +ntsysv-1.2.24-1 +db1-devel-1.85-7 +e2fsprogs-1.23-2 +iputils-20001110-6 +mingetty-0.9.4-18 +pwdb-0.61.1-3 +bash-2.05-8 +bzip2-1.0.1-4 +libstdc++-2.96-98 +logrotate-3.5.9-1 +rootfiles-7.2-1 +bash-doc-2.05-8 +iproute-2.2.4-14 +ncurses-5.2-12 +diffutils-2.7.2-2 +findutils-4.1.7-1 +gzip-1.3-15 +readline-4.2-2 +tmpwatch-2.8-2 +cpio-2.4.2-23 +gawk-3.1.0-3 +less-358-21 +procps-X11-2.0.7-11 +sed-3.02-10 +vim-minimal-5.8-7 +fileutils-4.1-4 +sysklogd-1.4.1-4 +mount-2.11g-5 +rpm-4.0.3-1.03 +glib-devel-1.2.10-5 +bzip2-libs-1.0.1-4 +tar-1.13.19-6 +cracklib-dicts-2.7-12 +passwd-0.64.1-7 +pam-devel-0.75-14 +SysVinit-2.78-19 +krb5-libs-1.2.2-13 +pam_krb5-1.46-1 +krbafs-utils-1.0.9-2 +setup-2.5.7-1 +basesystem-7.0-2 +glibc-2.2.4-13 +popt-1.6.3-1.03 +setuptool-1.8-2 +shadow-utils-20000902-4 +zlib-1.1.3-24 +chkconfig-1.2.24-1 +db1-1.85-7 +db3-3.2.9-4 +file-3.35-2 +losetup-2.11g-5 +net-tools-1.60-3 +netconfig-0.8.11-7 +libtermcap-2.0.8-28 +libtermcap-devel-2.0.8-28 +bzip2-devel-1.0.1-4 +libstdc++-devel-2.96-98 +modutils-2.4.6-4 +crontabs-1.10-1 +MAKEDEV-3.2-5 +grep-2.4.2-7 +psmisc-20.1-2 +readline-devel-4.2-2 +e2fsprogs-devel-1.23-2 +ed-0.2-21 +vim-common-5.8-7 +procps-2.0.7-11 +redhat-release-7.2-1 +time-1.7-14 +cracklib-2.7-12 +console-tools-19990829-36 +textutils-2.0.14-2 +dev-3.2-5 +glib-1.2.10-5 +termcap-11.0.1-10 +info-4.0b-3 +words-2-17 +pam-0.75-14 +util-linux-2.11f-9 +sh-utils-2.0.11-5 +initscripts-6.40-1 +krbafs-1.0.9-2 +krbafs-devel-1.0.9-2 diff --git a/doc/src/uml-rhroot.html b/doc/src/uml-rhroot.html new file mode 100644 index 000000000..ca05a2073 --- /dev/null +++ b/doc/src/uml-rhroot.html @@ -0,0 +1,116 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Building a RedHat root image</TITLE> + <!-- Created by: Michael Richardson, 22-Nov-2001 --> + <!-- Changed by: Michael Richardson, 22-Nov-2001 --> + + + </HEAD> + <BODY> + <H1>Building a RedHat root image</H1> + +<P> +The image required to use User-Mode-Linux is just a normal set of executables. +These can be extracted from a RedHat distribution using the following proceedure. +</P> + +<P> +There is a script in testing/utils called <CODE>uml-rhroot.sh</CODE>. It takes +two arguments: +<UL> +<LI> a directory in which to put resulting directory tree. +<LI> a directory tree containing the RedHat distribution RPMs. This may be + in one of three forms: +<UL> +<LI> a directory containing the directories "disc1" and "disc2". These + could be ISO images that are mounted loopback via, for instance: +<PRE> +<CODE> +mkdir -p /distros/redhat/7.2/disc1 /distros/redhat/7.2/disc1 +mount -t iso9660 -o loop,ro /distros/redhat/7.2/enigma-i386-disc1.iso /distros/redhat/7.2/disc1 +mount -t iso9660 -o loop,ro /distros/redhat/7.2/enigma-i386-disc2.iso /distros/redhat/7.2/disc2 +</CODE> +</PRE> +or even two real CDroms mounted somewhere. In the example above, use "/distros/redhat/7.2" as the distribution directory. +</LI> +<LI> a directory containing a "merged" disc1 and disc2 as suggested by RedHat in <A HREF="http://www.redhat.com/docs/manuals/linux/RHL-7.2-Manual/install-guide/s1-install-network.html#S2-INSTALL-SETUPSERVER">http://www.redhat.com/docs/manuals/linux/RHL-7.2-Manual/install-guide/s1-install-network.html under "Setting up the Server"</A>. +<LI> a directory containing all the required RPMs. (See <A HREF="uml-rhroot-list7.2.txt">list of RPMs</A>)</LI> +</UL> +</UL> +</P> + +<P>The unpacked distribution will take approximately 133Mb. You will + want to locate this on the same partition as your intended root + trees for your User-Mode-Linux's as this will permit hard links to + be used, saving disk space. +</P> + +<P> + Because the RPM command used uses the chroot(2) system call and + needs to change ownership of the files that it creates, it must be + run as root. Afterward, you should chown the entire directory to the + userid that you will be using for testing (i.e. probably + yours). It should eventually suffices to make sure that you can read + every file. +</P> + +<P> +You should be able to chroot to this directory and run programs. If +you can not at least run ls, then there is a problem. +</P> +<P> +Expect a couple of errors about install-info. +</P> + +<P> +An example: +<PRE> +<CODE> +Script started on Thu Nov 22 15:51:15 2001 +cassidy:/c2/user-mode-linux# df +Filesystem 1k-blocks Used Available Use% Mounted on +/dev/hda1 3844408 1673528 1975584 46% / +/dev/hda3 12495048 1823404 10036884 16% /home +/dev/hdc1 10325748 805056 8996172 9% /c1 +/dev/hdc2 10325780 4815160 4986100 50% /c2 +/dev/hdc3 10325780 2972480 6828780 31% /c3 +/dev/hdc4 7495084 3059640 4054704 44% /c4 +/distros/redhat/7.2/enigma-i386-disc1.iso + 662072 662072 0 100% /distros/redhat/7.2/disc1 +/distros/redhat/7.2/enigma-i386-disc2.iso + 653740 653740 0 100% /distros/redhat/7.2/disc2 +cassidy:/c2/user-mode-linux# /c2/freeswan/sandbox-main/testing/utils/uml-rhroot.sh +Usage: /c2/freeswan/sandbox-main/testing/utils/uml-rhroot.sh rootdir cdimagedir +cassidy:/c2/user-mode-linux# /c2/freeswan/sandbox-main/testing/utils/uml-rhroot.sh /c2/user-mode-linux/rpm-root/root /distros/redhat/7.2 +Assuming RH disc1 at /distros/redhat/7.2/disc1/RedHat/RPMS + and disc2 at /distros/redhat/7.2/disc2/RedHat/RPMS +/var/tmp/rpm-tmp.99149: /sbin/install-info: No such file or directory +error: execution of %post scriptlet from textutils-2.0.14-2 failed, exit status 127 +cat: /proc/mounts: No such file or directory +warning: /var/lib/rpm/Basenames created as /var/lib/rpm/Basenames.rpmnew +warning: /var/lib/rpm/Conflictname created as /var/lib/rpm/Conflictname.rpmnew +warning: /var/lib/rpm/Group created as /var/lib/rpm/Group.rpmnew +warning: /var/lib/rpm/Name created as /var/lib/rpm/Name.rpmnew +warning: /var/lib/rpm/Packages created as /var/lib/rpm/Packages.rpmnew +warning: /var/lib/rpm/Providename created as /var/lib/rpm/Providename.rpmnew +warning: /var/lib/rpm/Requirename created as /var/lib/rpm/Requirename.rpmnew +warning: /var/lib/rpm/Triggername created as /var/lib/rpm/Triggername.rpmnew +You should now chown it to yourself. +cassidy:/c2/user-mode-linux# chown -R mcr rpm-root/root +cassidy:/c2/user-mode-linux# ls rpm-root/root +bin dev home lib opt root tmp var +boot etc initrd mnt proc sbin usr +cassidy:/c2/user-mode-linux# chroot rpm-root/root +cassidy:/# ls +bin dev home lib opt root tmp var +boot etc initrd mnt proc sbin usr +cassidy:/# exit +cassidy:/c2/user-mode-linux# exit +Script done on Thu Nov 22 15:54:33 2001 +</CODE> +</PRE> + + + </BODY> +</HTML>
\ No newline at end of file diff --git a/doc/src/uml-stack-trace.html b/doc/src/uml-stack-trace.html new file mode 100644 index 000000000..1b08ed7d1 --- /dev/null +++ b/doc/src/uml-stack-trace.html @@ -0,0 +1,129 @@ +<PRE> +To: Michael Richardson <mcr@sandelman.ottawa.on.ca> +Cc: user-mode-linux-devel@lists.sourceforge.net +From: Jeff Dike <jdike@karaya.com> +Subject: [uml-devel] Re: stack trace +Date: Mon, 16 Sep 2002 22:36:06 -0500 + +mcr@sandelman.ottawa.on.ca said: +> Can you post (on list or web site) a "script" output of you trying to +> get the right stack out of a stuck uml (tracing myself)...? + +Yup. Here we go... + +Here, I attach to the tracing thread and get the stack of the current thread, +which happens to be the idle thread. + +um 1013: gdb linux 14936 +GNU gdb 5.0rh-5 Red Hat Linux 7.1 +Copyright 2001 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, and you are +welcome to change it and/or distribute copies of it under certain conditions. +Type "show copying" to see the conditions. +There is absolutely no warranty for GDB. Type "show warranty" for details. +This GDB was configured as "i386-redhat-linux"... +/home/jdike/linux/2.4/um/14936: No such file or directory. +Attaching to program: /home/jdike/linux/2.4/um/linux, process 14936 +0xa014efe9 in __wait4 () + +# This is how you get the current task in the tracing thread - get_current() +# only works in a kernel thread. +(gdb) p (struct task_struct *)cpu_tasks[0].task +$2 = (struct task_struct *) 0xa01c0000 + +# Get the host pid of that task. +(gdb) p $2.thread.extern_pid +$3 = 14939 + +# Get the current ip and sp. +(gdb) shell cat /proc/14939/stat +14939 (linux) T 14936 14936 883 34816 14936 64 5 3 806 7 62 12 0 0 9 0 0 2 +588043 142770176 5008 4294967295 2684358656 2686348640 3221223520 2686205764 + sp ^^^^^^^^^^ + 2685727185 73728 201392128 167776768 268444672 3222308129 0 0 17 0 +ip ^^^^^^^^^^ + +# the sp and ip are items 4 and 5 after the 4294967295 (on 2.2 hosts, that's +2^31 - 1 rather than 2^32 - 1). + +(gdb) p/x 2686205764 +$4 = 0xa01c3f44 +(gdb) p/x 2685727185 +$5 = 0xa014f1d1 + +# Where's the ip? +(gdb) i sym 0xa014f1d1 +nanosleep + 17 in section .text + +# look at the stack around the sp +(gdb) x/32x 0xa01c3f30 +0xa01c3f30 : 0x00000000 0x00000000 0xa01c3f60 0xa00020a8 +0xa01c3f40 : 0x00000004 0xa012e891 0xa01c3f58 0xa01c3f58 +0xa01c3f50 : 0xa01c3f70 0xa0023667 0x00000009 0x3b023380 +0xa01c3f60 : 0xa01c3fa0 0xa012a21d 0x0000000a 0xa01c0000 +0xa01c3f70 : 0xa01c3fa0 0xa012a213 0x00000003 0x00000024 +0xa01c3f80 : 0xa01c3fa0 0xa0011bc4 0xa012b25c 0x00000000 +0xa01c3f90 : 0xa01c3fb0 0x00000000 0xa01c3ffc 0x0000000d +0xa01c3fa0 : 0xa01c3fb0 0xa000c50e 0xa01812e0 0xa01c3ffc + +# The trick here is to locate a frame near the current sp. You're looking +# for a consecutive pair of longwords (fp, ip) having the properties that: +# fp is on the current kernel stack and points further up it +# ip is a text address (if you can't recognize a UML text address by +# sight, print out &_stext and &_etext) +# +# Starting at 0xa01c3f44, the first pair of works satisfying these requirements +# is at 0xa01c3f50. +# So, print that pair out as hex. +(gdb) p/x *((int (*)[2])0xa01c3f50) +$9 = {0xa01c3f70, 0xa0023667} + +# Now, we start climbing the stack. +(gdb) p/x *((int (*)[2])$[0]) +$10 = {0xa01c3fa0, 0xa012a213} +(gdb) +$11 = {0xa01c3fb0, 0xa000c50e} +(gdb) +$12 = {0xa01c3fc0, 0xa000356d} +(gdb) +$13 = {0xa01c3fd0, 0xa013082f} +(gdb) +$14 = {0xa01c3ff0, 0xa012fbdd} +# Stop when you see a NULL frame pointer or gdb bitches at you. +(gdb) +$15 = {0x0, 0xa01513aa} + +# Now we get the symbolic version of the stack with 'i sym' of the second item +# in each pair. +(gdb) i sym 0xa0023667 +check_pgt_cache + 23 in section .text +(gdb) i sym 0xa012a213 +cpu_idle + 123 in section .text +(gdb) i sym 0xa000c50e +rest_init + 46 in section .text +(gdb) i sym 0xa000356d +start_kernel + 361 in section .text.init +(gdb) i sym 0xa013082f +start_kernel_proc + 63 in section .text +(gdb) i sym 0xa012fbdd +signal_tramp + 209 in section .text +(gdb) i sym 0xa01513aa +thread_start + 4 in section .text + +# You can also get line number information with 'i line'. +(gdb) i line *0xa012a213 +Line 488 of "process_kern.c" starts at address 0xa012a213 <cpu_idle+123> + and ends at 0xa012a21d <cpu_idle+133>. +(gdb) + + +------------------------------------------------------- +Sponsored by: AMD - Your access to the experts on Hammer Technology! +Open Source & Linux Developers, register now for the AMD Developer +Symposium. Code: EX8664 http://www.developwithamd.com/developerlab +_______________________________________________ +User-mode-linux-devel mailing list +User-mode-linux-devel@lists.sourceforge.net +https://lists.sourceforge.net/lists/listinfo/user-mode-linux-devel + +</PRE>
\ No newline at end of file diff --git a/doc/src/umltesting.html b/doc/src/umltesting.html new file mode 100644 index 000000000..df62a9ae2 --- /dev/null +++ b/doc/src/umltesting.html @@ -0,0 +1,478 @@ +<html> +<head> +<title>FreeS/WAN User-Mode-Linux testing guide</title> +<!-- Changed by: Michael Richardson, 05-Mar-2003 --> +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, testing, User-Mode-Linux, UML"> + +<!-- + +Written by Michael Richardson for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +$Id: umltesting.html,v 1.1 2004/03/15 20:35:24 as Exp $ + +$Log: umltesting.html,v $ +Revision 1.1 2004/03/15 20:35:24 as +added files from freeswan-2.04-x509-1.5.3 + +Revision 1.23 2003/09/18 15:12:11 dhr + +fix link to kernel.org mirrors page + +Revision 1.22 2003/03/07 03:49:25 dhr + +fix recommended version of uml-patch + +Revision 1.21 2003/03/06 08:37:03 dhr + +capture more of MCR's knowledge about BIND + +Revision 1.20 2003/03/06 02:15:44 mcr + added note about need for bind9. + +Revision 1.19 2003/03/05 23:20:39 mcr + updates from -47 to -53. + +Revision 1.18 2003/02/27 08:25:48 dhr + +update to reflect newer umlfreeroot + +Revision 1.17 2003/02/27 08:16:45 dhr + +make clear what is the latest version of the UML patch that we've used + +Revision 1.16 2003/02/21 01:35:31 mcr + updated latest umlfreeroot to 15.1. + +Revision 1.15 2003/01/21 03:26:34 mcr + updated documentation on UML state. + +Revision 1.14 2002/11/11 16:43:35 mcr + adjusted formatting of uml_netjig notes. + +Revision 1.13 2002/11/08 10:13:05 mcr + updated documentation for 2.4.19 + +Revision 1.12 2002/11/03 23:44:23 mcr + fixed some formatting in umltesting.html + added some notes about NETJIGWAITUSER re: having tests + prompt before they exit. Helps with debugging. + +Revision 1.11 2002/10/31 19:01:31 mcr + documentation for RUN_*_SCRIPT. + +Revision 1.10 2002/09/15 23:57:59 dhr + +update suggested umlfreeroot + +Revision 1.9 2002/09/15 19:28:05 mcr + added some comments about problems with UMLs. + +Revision 1.8 2002/09/11 20:00:25 mcr + updated umlroot rev to 8.0. + +Revision 1.7 2002/09/09 21:37:43 mcr + updated document to reference currently working kernel+UML. + +Revision 1.6 2002/08/02 22:43:35 mcr + added section on debugging with UMLs. + +Revision 1.5 2002/05/30 18:47:57 dhr + +Update from experience: +- fixed HTML bugs +- restructure slightly +- added another intro paragraph +- mentioned lack of Super User requirements +- added tcpdump build and install procedure +- added uml utils build procedure +- added invitation to try "make check" +- fixed minor typos and mistakes + +Revision 1.4 2002/03/12 21:10:37 mcr + removed instruction on downloading umlminishare, as this is + now simply included in umlrootXXX. reformated some other text. + +Revision 1.3 2002/01/29 02:21:21 mcr + updated instructions for 2.4.17, and for newest UMLroot. + +Revision 1.2 2001/11/27 05:24:09 mcr + added reference to uml-rhroot, but commented out. + This proceedure is not yet ready for prime time. + +Revision 1.1 2001/11/05 04:35:57 mcr + adapted text from design list posting into HTML for Sandy. + + +--> +</head> + +<body> + +<h1><a name="umltesting">User-Mode-Linux Testing guide</a></h1> + +<p> +User mode linux is a way to compile a linux kernel such that it can run as a +process in another linux system (potentially as a *BSD or Windows process +later). See <A HREF="http://user-mode-linux.sourceforge.net/">http://user-mode-linux.sourceforge.net/</A> +</P> + +<p> +UML is a good platform for testing and experimenting with FreeS/WAN. +It allows several network nodes to be simulated on a single machine. +Creating, configuring, installing, monitoring, and controling these +nodes is generally easier and easier to script with UML than real +hardware. +</p> + +<p> +You'll need about 500Mb of disk space for a full sunrise-east-west-sunset +setup. You can possibly get this down by 130Mb if you remove the +sunrise/sunset kernel build. If you just want to run, then you can even +remove the east/west kernel build. +</p> +<p> +Nothing need be done as super user. In a couple of steps, we note +where super user is required to install commands in system-wide +directories, but ~/bin could be used instead. UML seems to use a +system-wide /tmp/uml directory so different users may interfere with +one another. Later UMLs use ~/.uml instead, so multiple users running UML +tests should not be a problem, but note that a single user running +the UML tests will only be able run one set. Further, UMLs sometimes +get stuck and hang around. These "zombies" (most will actually be in +the "T" state in the process table) will interfere with subsequent tests. +</P> +<H2>Preliminary Notes on BIND</H2> + +<P> +As of 2003/3/1, the Light-Weight Resolver is used by pluto. This requires +that BIND9 be running. It also requires that BIND9 development libraries +be present in the build environment. The DNSSEC code is only truly functional +in BIND9 snapshots. The library code could be 9.2.2, we believe. We are +using BIND9 20021115 snapshot code from +<A HREF="ftp://ftp.isc.org/isc/bind9/snapshots">ftp://ftp.isc.org/isc/bind9/snapshots</A>. +</P> +<P> +FreeS/WAN may well require a newer BIND than is on your system. +Many distributions have moved to BIND9.2.2 recently due to a security advisory. +BIND is five components. +</P> +<OL> +<LI> +named +</LI> +<LI> +dnssec-* +</LI> +<LI> +client side resolver libraries +</LI> +<LI> +client side utility libraries +I thought there were lib and named parts to dnsssec... +</LI> +<LI> +dynamic DNS update utilities +</LI> +</OL> +<P> +The only piece that we need for *building* is #4. That's the only part that has to be on the build host. +What is the difference between resolver and util libs? +If you want to edit testing/baseconfigs/all/etc/bind, you'll need a snapshot version. +The resolver library contains the resolver. +FreeS/WAN has its own copy of that in lib/liblwres. +</P> +<H2>Steps to Install UML for FreeS/WAN</H2> +<OL> +<LI> Get the following files: +<OL type="a"> +<LI> from <A HREF="http://www.sandelman.ottawa.on.ca/freeswan/uml/">http://www.sandelman.ottawa.on.ca/freeswan/uml/</A> +umlfreeroot-15.1.tar.gz (or highest numbered one). This is a + debian potato root file system. You can use this even on a Redhat + host, as it has the newer GLIBC2.2 libraries as well. + + +<!-- If you are using + Redhat 7.2 or newer as your development machine, you can create the + image from your installation media. See <A HREF="uml-rhroot.html">Building a RedHat root"></A>. + A future document will explain how to build this from .DEB files as well. +--> + +<!-- +<LI> umlfreesharemini.tar.gz (or umlfreeshareall.tar.gz). + If you are a Debian potato user, you don't need it you can use your + native /usr/share. +</UL> +--> + +<LI> From <A HREF="ftp://ftp.xs4all.nl/pub/crypto/freeswan/">ftp://ftp.xs4all.nl/pub/crypto/freeswan/</A> +a snapshot or release (1.92 or better) + +<LI> From a + <A HREF="http://www.kernel.org/mirrors/">http://www.kernel.org mirror</A>, + the virgin 2.4.19 kernel. Please realize that we have defaults in our + tree for kernel configuration. We try to track the latest UML + kernels. If you use a newer kernel, you may have faults in the + kernel build process. You can see what the latest that is being regularly tested by visiting <A HREF="http://bugs.freeswan.org:81/regress/HEAD/lastgood/freeswan-regress-env.sh">freeswan-regress-env.sh</A>. + +<LI> +<!-- Note: this step is refered to as "step 1d" below. --> +Get + <A HREF="http://ftp.nl.linux.org/uml/">http://ftp.nl.linux.org/uml/</A> + uml-patch-2.4.19-47.bz2 or the one associated with your kernel. + As of 2003/03/05, uml-patch-2.4.19-47.bz2 works for us. +<STRONG>More recent versions of the patch have not been tested by us.</STRONG> +<LI> You'll probably want to visit +<A + HREF="http://user-mode-linux.sourceforge.net">http://user-mode-linux.sourceforge.net</A> +and get the UML utilities. These are not needed for the build or interactive use (but recommended). They are necessary for the regression testing procedures used by "make check". +We currently use uml_utilities_20020212.tar.bz2. +<LI> +You need tcpdump version 3.7.1 or better. +This is newer than the version included in most LINUX distributions. +You can check the version of an installed tcpdump with the --version flag. +If you need a newer tcpdump +fetch both tcpdump and libpcap source tar files from +<A HREF="http://www.tcpdump.org/">http://www.tcpdump.org/</A> or a mirror. +</OL> + +<LI> Pick a suitable place, and extract the following files: +<OL type="a"> +<LI> +<!-- Note: this step is refered to as "step 2a" later. --> +2.4.19 kernel. For instance: +<PRE> +<CODE> + cd /c2/kernel + tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz +</CODE> +</PRE> + +<LI> extract the umlfreeroot file +<!-- (unless you <A HREF="uml-rhroot.html">built your own from RPMs</A>) --> +<PRE> +<CODE> + mkdir -p /c2/user-mode-linux/basic-root + cd /c2/user-mode-linux/basic-root + tar xzvf ../download/umlfreeroot-15.1.tar.gz +</CODE> +</PRE> + +<LI> FreeSWAN itself (or checkout "all" from CVS) +<PRE> +<CODE> + mkdir -p /c2/freeswan/sandbox + cd /c2/freeswan/sandbox + tar xzvf ../download/snapshot.tar.gz +</CODE> +</PRE> +</OL> + +<LI> If you need to build a newer tcpdump: +<UL> +<LI> +Make sure you have OpenSSL installed -- it is needed for cryptographic routines. +<LI> +Unpack libpcap and tcpdump source in parallel directories (the tcpdump +build procedures look for libpcap next door). +<LI> +Change directory into the libpcap source directory and then build the library: +<PRE> +<CODE> + ./configure + make +</CODE> +</PRE> +<LI> +Change into the tcpdump source directory, build tcpdump, and install it. +<PRE> +<CODE> + ./configure + make + # Need to be superuser to install in system directories. + # Installing in ~/bin would be an alternative. + su -c "make install" +</CODE> +</PRE> +</UL> +<LI> If you need the uml utilities, unpack them somewhere then build and install +them: +<PRE> +<CODE> + cd tools + make all + # Need to be superuser to install in system directories. + # Installing in ~/bin would be an alternative. + su -c "make install BIN_DIR=/usr/local/bin" +</CODE> +</PRE> +<LI> set up the configuration file +<UL> +<LI> +<CODE> +cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils +</CODE> +<LI> copy umlsetup-sample.sh to ../../umlsetup.sh: +<CODE> + cp umlsetup-sample.sh ../../umlsetup.sh +</CODE> + +<LI> open up ../../umlsetup.sh in your favorite editor. +<LI> change POOLSPACE= to point to the place with at least 500Mb of +disk. Best if it is on the same partition as the "umlfreeroot" extraction, +as it will attempt to use hard links if possible to save disk space. + +<LI> Set TESTINGROOT if you intend to run the script outside of the + sandbox/snapshot/release directory. Otherwise, it will configure itself. + +<LI> KERNPOOL should point to the directory with your 2.4.19 kernel + tree. This tree should be unconfigured! This is the directory + you used in step 2a. + +<LI> UMLPATCH should point at the bz2 file you downloaded at 1d. + If using a kernel that already includes the patch, set this to /dev/null. + +<LI> FREESWANDIR should point at the directory where you unpacked + the snapshot/release. Include the "freeswan-snap2001sep16b" + or whatever in it. If you are running from CVS, then + you point at the directory where top, klips, etc. are. + The script will fix up the directory so that it can be + used. + +<LI> BASICROOT should be set to the directory used in 2b, or to the directory + that you created with RPMs. + +<LI> SHAREDIR should be set to the directory used in 2c, to /usr/share + for Debian potato users, or to $BASICROOT/usr/share. +</UL> + +<LI> <PRE><CODE> +cd $TESTINGROOT/utils +sh make-uml.sh +</CODE></PRE> + It will grind for awhile. If there are errors it will bail. + If so, run it under "script" and send the output to bugs@lists.freeswan.org. + +<LI> You will have a bunch of stuff under $POOLSPACE. + Open four xterms: + +<PRE><CODE> + for i in sunrise sunset east west + do + xterm -name $i -title $i -e $POOLSPACE/$i/start.sh & + done +</CODE></PRE> + +<LI> Login as root. Password is "root" + (Note, these virtual machines are networked together, but are not + configured to talk to the rest of the world.) + +<LI> verify that pluto started on east/west, run "ipsec look" + +<LI> login to sunrise. run "ping sunset" + +<LI> login to west. run "tcpdump -p -i eth1 -n" + (tcpdump must be version 3.7.1 or newer) + +<LI> Closing a console xterm will shut down that UML. + +<LI> You can "make check", if you want to. +It is run from /c2/freeswan/sandbox/freeswan-1.97.</LI> + +</OL> + +<H1>Debugging the kernel with GDB</H1> + +<P> +With User-Mode-Linux, you can debug the kernel using GDB. +See <HREF="http://user-mode-linux.sourceforge.net/debugging.html">http://user-mode-linux.sourceforge.net/debugging.html</A>. +</P> + +<P> +Typically, one will want to address a test case for a failing situation. +Running GDB from Emacs, or from other front ends is possible. First start GDB. +</P> +<P> +Tell it to open the UMLPOOL/swan/linux program. +</P> +<P> +Note the PID of GDB: +<PRE> +marajade-[projects/freeswan/mgmt/planning] mcr 1029 %ps ax | grep gdb + 1659 pts/9 SN 0:00 /usr/bin/gdb -fullname -cd /mara4/freeswan/kernpatch/UMLPOOL/swan/ linux +</PRE> +</P> + +<P> +Set the following in the environment: +<PRE> +UML_east_OPT="debug gdb-pid=1659" +</PRE> +</P> + +<P> +Then start the user-mode-linux in the test scheme you wish: +<PRE> +marajade-[kernpatch/testing/klips/east-icmp-02] mcr 1220 %../../utils/runme.sh +</PRE> + +The user-mode-linux will stop on boot, giving you a chance to attach to the process: + +<PRE> +(gdb) file linux +Reading symbols from linux...done. +(gdb) attach 1 +Attaching to program: /mara4/freeswan/kernpatch/UMLPOOL/swan/linux, process 1 +0xa0118bc1 in kill () at hostfs_kern.c:770 +</PRE> + +<P> +At this point, break points should be created as appropriate. +</P> + +<H2>Other notes about debugging</H2> + +<P> +If you are running a standard test, after all the packets are sent, the UML will +be shutdown. This can cause problems, because the UML may get terminated while you +are debugging. +</P> +<P> +The environment variable <CODE>NETJIGWAITUSER</CODE> can be set to "waituser". +If so, then the testing system will prompt before exiting the test. +</P> + +<H1>User-Mode-Linux mysteries</H1> + +<UL> +<LI> running more than one UML of the same name (e.g. "west") can cause + problems. +<LI> running more than one UML from the same root file system is not + a good idea. +<LI> all this means that running "make check" twice on the same machine + is probably not a good idea. +<LI> occationally, UMLs will get stuck. This can happen like: +<BLOCK> +15134 ? T 0:00 /spare/hugh/uml/uml2.4.18-sept5/umlbuild/east/linux (east) [/bin/sh] +15138 ? T 0:00 /spare/hugh/uml/uml2.4.18-sept5/umlbuild/east/linux (east) [halt] + </BLOCK> + +these will need to be killed. Note that they are in "T"racing mode. +<LI> UMLs can also hang, and will report "Tracing myself and I can't get out". +This is a bug in UML. There are ways to find out what is going on and +report this to the UML people, but we don't know the magic right now. +</UL> + +<H1>Getting more info from uml_netjig</H1> + +<P> +uml_netjig can be compiled with a built-in tcpdump. This uses not-yet-released +code from <A HREF="http://www.tcpdump.org/">www.tcpdump.org</A>. +Please see the instructions in <CODE>testing/utils/uml_netjig/Makefile</CODE>. +</P> + +</body> +</html> diff --git a/doc/src/upgrading.html b/doc/src/upgrading.html new file mode 100644 index 000000000..0d6401b96 --- /dev/null +++ b/doc/src/upgrading.html @@ -0,0 +1,260 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>Introduction to FreeS/WAN</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, encryption, cryptography, FreeS/WAN, FreeSWAN"> + <!-- + + Written by Claudia Schmeing for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: upgrading.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<A NAME="upgrading"></A><h1>Upgrading to FreeS/WAN 2.x</h1> + + +<H2>New! Built in Opportunistic connections</H2> + +<P>Out of the box, FreeS/WAN 2.x will attempt to encrypt all your IP traffic. +It will try to establish IPsec connections for:</P> +<UL><LI> +IP traffic from the Linux box on which you have installed FreeS/WAN, and</LI> +<LI> +outbound IP traffic routed through that Linux box (eg. from a protected subnet).</LI> +</UL> +<P>FreeS/WAN 2.x uses <STRONG>hidden, automatically enabled + <VAR>ipsec.conf</VAR> connections</STRONG> to do this.</P> + +<P>This behaviour is part of our campaign to get Opportunistic +Encryption (OE) widespread in the Linux world, so that any two Linux boxes can +encrypt to one another without prearrangement. +There's one catch, however: you must <A HREF="quickstart.html#quickstart">set +up a few DNS records</A> +to distribute RSA public keys and (if applicable) IPsec gateway +information.</P> + +<P>If you start FreeS/WAN before you have set up these DNS +records, your connectivity will be slow, and +messages relating to the built in connections will clutter your logs. +If you are unable to set up DNS for OE, you will wish to +<A HREF="policygroups.html#disable_policygroups">disable the +hidden connections</A>.</P> + +<A NAME="upgrading.flagday"></A> + +<H3>Upgrading Opportunistic Encryption +to 2.01 (or later)</H3> + +<P>As of FreeS/WAN 2.01, Opportunistic Encryption (OE) +uses DNS TXT resource records (RRs) only (rather than TXT with KEY). +This change causes a "flag day". +Users of FreeS/WAN 2.00 (or earlier) OE who are upgrading may +need to post additional resource records. +</P> + +<P>If you are running +<A HREF="glossary.html#initiate-only">initiate-only OE</A>, +you <em>must</em> put up a TXT record in any forward domain as per our +<A HREF="quickstart.html#opp.client">quickstart instructions</A>. This +replaces your old forward KEY. +</P> + +<P> +If you are running full OE, you require no updates. You already have +the needed TXT record in the reverse domain. +However, to facilitate future features, you +may also wish to publish that TXT record in a forward domain as +instructed <A HREF="quickstart.html#opp.incoming">here</A>. +</P> + +<P>If you are running OE on a gateway (and encrypting on behalf of subnetted +boxes) you require no updates. +You already have the required TXT record in your gateway's reverse map, +and the TXT records for any subnetted boxes require no updating. +However, to facilitate future features, you may wish to publish your gateway's + TXT record in a forward domain as shown +<A HREF="quickstart.html#opp.incoming">here</A>. + + +<P> +During the transition, you may wish to leave any old KEY records up for +some time. They will provide limited backward compatibility. +<!-- +For more +detail on that compatibility, see <A HREF="oe.known-issues">Known Issues with +OE</A>. +--> +</P> + +<H2>New! Policy Groups</H2> + +<P>We want to make it easy for you to declare security policy as it +applies to IPsec connections.</P> + +<P>Policy Groups make it simple to say: +</P> + +<UL> +<LI>These are the folks I want to talk to in the clear.</LI> +<LI>These spammers' domains -- I don't want to talk to them at all.</LI> +<LI>To talk to the finance department, I must use IPsec.</LI> +<LI>For any other communication, try to encrypt, but it's okay if we can't.</LI></UL> + +<P>FreeS/WAN then implements these policies, creating OE connections +if and when needed. +You can use Policy Groups along with connections you explicitly +define in ipsec.conf.</P> + +<P>For more information, see our +<A HREF="policygroups.html">Policy Group HOWTO</A>.</P> + + +<H2>New! Packetdefault Connection</H2> + +<P>Free/SWAN 2.x ships with the <STRONG>automatically enabled, hidden +connection</STRONG> <VAR>packetdefault</VAR>. This configures +a FreeS/WAN box as an OE gateway for any hosts located +behind it. As mentioned above, you must configure some +<A HREF="quickstart.html">DNS records</A> for +OE to work.</P> +<P>As the name implies, this connection functions as a default. If you +have more specific connections, such as policy groups which configure +your FreeS/WAN box as an OE gateway for a local subnet, these +will apply before <VAR>packetdefault</VAR>. You can view +<VAR>packetdefault</VAR>'s specifics in +<A HREF="manpage.d/ipsec.conf.5.html">man ipsec.conf</A>. +</P> + + +<H2>FreeS/WAN now disables Reverse Path Filtering</H2> + +<P>FreeS/WAN often doesn't work with reverse path filtering. At +start time, FreeS/WAN now turns rp_filter off, and logs a warning.</P> + +<P>FreeS/WAN does not turn it back on again. +You can do this yourself with a command like:</P> + +<PRE> echo 1 > /proc/sys/net/ipv4/conf/eth0/rp_filter</PRE> + +<P>For eth0, substitute the interface which FreeS/WAN was affecting.</P> + + +<A NAME="ipsec.conf_v2"></A><H2>Revised <VAR>ipsec.conf</VAR></H2> + +<H3>No promise of compatibility</H3> + +<P>The FreeS/WAN team promised config-file compatibility throughout +the 1.x series. That means a 1.5 config file can be directly imported into +a fresh 1.99 install with no problems.</P> + +<P>With FreeS/WAN 2.x, we've given ourselves permission to make the config +file easier to use. The cost: some FreeS/WAN 1.x configurations will not +work properly. Many of the new features are, however, backward compatible.</P> + + +<H3>Most <VAR>ipsec.conf</VAR> files will work fine</H3> + +<P>... so long as you paste this line, <STRONG>with no preceding +whitespace</STRONG>, + at the top of your config file: +</P> + +<PRE> version 2</PRE> + +<H3>Backward compatibility patch</H3> + +<P>If the new defaults bite you, use +<A HREF="ipsec.conf.2_to_1"> +this <VAR>ipsec.conf</VAR> fragment</A> to simulate the old default values.</P> + + +<H3>Details</H3> + +<P> +We've obsoleted various directives which almost no one was using: +</P> +<PRE> dump + plutobackgroundload + no_eroute_pass + lifetime + rekeystart + rekeytries</PRE> + +<P>For most of these, there is some other way to elicit the desired behaviour. +See <A HREF="http://lists.freeswan.org/pipermail/design/2002-August/003243.html"> +this post</A>. + +<P> +We've made some settings, which almost everyone was using, defaults. +For example: +</P> + +<PRE> interfaces=%defaultroute + plutoload=%search + plutostart=%search + uniqueids=yes</PRE> + +<P>We've also changed some default values to help with OE and Policy Groups:</P> + +<PRE> authby=rsasig ## not secret!!! + leftrsasigkey=%dnsondemand ## looks up missing keys in DNS when needed. + rightrsasigkey=%dnsondemand</PRE> + +<P> +Of course, you can still override any defaults by explictly declaring something +else in your connection. +</P> + +<P> +<A HREF="http://lists.freeswan.org/pipermail/design/2002-August/003243.html">A post with a list of many ipsec.conf changes.</A><BR> +<A HREF="manpage.d/ipsec.conf.5.html">Current ipsec.conf manual.</A> +</P> + + +<A NAME="upgrading.rpms"></A><H3>Upgrading from 1.x RPMs to 2.x RPMs</H3> + +<P>Note: When upgrading from 1-series to 2-series RPMs, +<VAR>rpm -U</VAR> will not work.</P> + +<P>You must instead erase the 1.x RPMs, then install the 2.x set:</P> +<PRE> rpm -e freeswan</PRE> +<PRE> rpm -e freeswan-module</PRE> + +<P>On erasing, your old <VAR>ipsec.conf</VAR> should be moved to +<VAR>ipsec.conf.rpmsave</VAR>. +Keep this. You will probably want to copy your existing connections to the +end of your new 2.x file.</P> + +<P>Install the RPMs suitable for your kernel version, such as:</P> +<PRE> rpm -ivh freeswan-module-2.04_2.4.20_20.9-0.i386.rpm</PRE> +<PRE> rpm -ivh freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm</PRE> + + + +<P>Or, to splice the files:</P> + +<PRE> cat /etc/ipsec.conf /etc/ipsec.conf.rpmsave > /etc/ipsec.conf.tmp + mv /etc/ipsec.conf.tmp /etc/ipsec.conf</PRE> + +<P>Then, remove the redundant <VAR>conn %default</VAR> and +<VAR>config setup</VAR> +sections. Unless you have done any special configuring here, you'll likely +want to remove the 1.x versions. Remove <VAR>conn OEself</VAR>, if +present.</P> + + + +</body> +</html> diff --git a/doc/src/user_examples.html b/doc/src/user_examples.html new file mode 100755 index 000000000..5e3784858 --- /dev/null +++ b/doc/src/user_examples.html @@ -0,0 +1,322 @@ +<html> +<head> +<title>FreeS/WAN examples</title> +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, examples"> + +<!-- + +Written by Sandy Harris for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +CVS information: +RCS ID: $Id: user_examples.html,v 1.1 2004/03/15 20:35:24 as Exp $ +Last changed: $Date: 2004/03/15 20:35:24 $ +Revision number: $Revision: 1.1 $ + +CVS revision numbers do not correspond to FreeS/WAN release numbers. +--> +</head> + +<body> + +<h1><a name="user.examples">FreeS/WAN script examples</a></h1> + +This file is intended to hold a collection of user-written example +scripts or configuration files for use with FreeS/WAN. +<p> +So far it has only one entry. + +<h2><a name="poltorak">Poltorak's Firewall script</a></h2> + +<pre> +From: Poltorak Serguei <poltorak@dataforce.net> +Subject: [Users] Using FreeS/WAN +Date: Tue, 16 Oct 2001 + +Hello. + +I'm using FreeS/WAN IPsec for half a year. I learned a lot of things about +it and I think it would be interesting for someone to see the result of my +experiments and usage of FreeS/WAN. If you find a mistake in this +file, please e-mail me. And excuse me for my english... I'm learning.. :) + +I'll talk about vary simple configuration: + +addresses prefix = 192.168 + + lan1 sgw1 .0.0/24 (Internet) sgw2 lan2 + .1.0/24---[ .1.1 ; .0.1 ]===================[ .0.10 ; . 2.10 ]---.2.0/24 + + +We need to let lan1 see lan2 across Internet like it is behind sgw1. The +same for lan2. And we need to do IPX bridge for Novel Clients and NDS +synchronization. + +my config: +------------------- ipsec.conf ------------------- +conn lan1-lan2 + type=tunnel + compress=yes + #------------------- + left=192.168.0.1 + leftsubnet=192.168.1.0/24 + #------------------- + right=192.168.0.10 + rightsubnet=192.168.2.0/24 + #------------------- + auth=esp + authby=secret +--------------- end of ipsec.conf ---------------- + +ping .2.x from .1.y (y != 1) +It works?? Fine. Let's continue... + +Why y != 1 ?? Because kernel of sgw1 have 2 IP addresses and it will choose +the first IP (which is used to go to Internet) .0.1 and the packet won't go +through IPsec tunnel :( But if do ping on .1.1 kernel will respond from +that address (.1.1) and the packet will be tunneled. The same problem occurred then +.2.x sends a packet to .1.2 which is down at the moment. What happens? .1.1 +sends ARP requesting .1.2... after 3 tries it send to .2.x an destunreach, +but from his "natural" IP or .0.1 . So the error message won't be delivered! +It's a big problem... + +Resolution... One can manipulate with ipsec0 or ipsec0:0 to solve the +problem (if ipsec0 has .1.1 kernel will send packets correctly), but there +are powerful and elegant iproute2 :) We simply need to change source address +of packet that goes to other secure lan. This is done with + +ip route replace 192.168.2.0/24 via 192.168.0.10 dev ipsec0 src 192.168.1.1 + +Cool!! Now it works!! + +The second step. We want install firewall on sgw1 and sgw2. Encryption of +traffic without security isn't a good idea. I don't use {left|right}firewall, +because I'm running firewall from init scripts. + +We want IPsec data between lan1-lan2, some ICMP errors (destination +unreachable, TTL exceeded, parameter problem and source quench), replying on +pings from both lans and Internet, ipxtunnel data for IPX and of course SSH +between sgw1 and sgw2 and from/to one specified host. + +I'm using ipchains. With iptables there are some changes. + +---------------- rc.firewall --------------------- +#!/bin/sh +# +# Firewall for IPsec lan1-lan2 +# + +IPC=/sbin/ipchains +ANY=0.0.0.0/0 + +# left +SGW1_EXT=192.168.0.1 +SGW1_INT=192.168.1.1 +LAN1=192.168.1.0/24 + +# right +SGW2_EXT=192.168.0.10 +SGW2_INT=192.168.2.10 +LAN2=192.168.2.0/24 + +# SSH from and to this host +SSH_PEER_HOST=_SOME_HOST_ + +# this is for left. exchange these values for right. +MY_EXT=$SGW1_EXT +MY_INT=$SGW1_INT +PEER_EXT=$SGW2_EXT +PEER_INT=$SGW2_INT +INT_IF=eth1 +EXT_IF=eth0 +IPSEC_IF=ipsec0 +MY_LAN=$LAN1 +PEER_LAN=$LAN2 + +$IPC -F +$IPC -P input DENY +$IPC -P forward DENY +$IPC -P output DENY + +# Loopback traffic +$IPC -A input -i lo -j ACCEPT +$IPC -A output -i lo -j ACCEPT + +# for IPsec SGW1-SGW2 +## IKE +$IPC -A input -p udp -s $PEER_EXT 500 -d $MY_EXT 500 -i $EXT_IF -j ACCEPT +$IPC -A output -p udp -s $MY_EXT 500 -d $PEER_EXT 500 -i $EXT_IF -j ACCEPT +## ESP +$IPC -A input -p 50 -s $PEER_EXT -d $MY_EXT -i $EXT_IF -j ACCEPT +### we don't need this line ### $IPC -A output -p 50 -s $MY_EXT -d $PEER_EXT -i $EXT_IF -j ACCEPT +## forward LAN1-LAN2 +$IPC -A forward -s $MY_LAN -d $PEER_LAN -i $IPSEC_IF -j ACCEPT +$IPC -A forward -s $PEER_LAN -d $MY_LAN -i $INT_IF -j ACCEPT +$IPC -A output -s $PEER_LAN -d $MY_LAN -i $INT_IF -j ACCEPT +$IPC -A input -s $PEER_LAN -d $MY_LAN -i $IPSEC_IF -j ACCEPT +$IPC -A input -s $MY_LAN -d $PEER_LAN -i $INT_IF -j ACCEPT +$IPC -A output -s $MY_LAN -d $PEER_LAN -i $IPSEC_IF -j ACCEPT + +# ICMP +# +## Dest unreachable +### from/to Internet +$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT +### from/to Lan +$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT +### from/to Peer Lan +$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT +# +## Source quench +### from/to Internet +$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type source-quench -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT +### from/to Lan +$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type source-quench -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT +### from/to Peer Lan +$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type source-quench -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT +# +## Parameter problem +### from/to Internet +$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT +### from/to Lan +$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT +### from/to Peer Lan +$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT +# +## Time To Live exceeded +### from/to Internet +$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT +### to Lan +$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT +### to Peer Lan +$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT +$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT + +# ICMP PINGs +## from Internet +$IPC -A input -p icmp -s $ANY -d $MY_EXT --icmp-type echo-request -i $EXT_IF -j ACCEPT +$IPC -A output -p icmp -s $MY_EXT -d $ANY --icmp-type echo-reply -i $EXT_IF -j ACCEPT +## from LAN +$IPC -A input -p icmp -s $ANY -d $MY_INT --icmp-type echo-request -i $INT_IF -j ACCEPT +$IPC -A output -p icmp -s $MY_INT -d $ANY --icmp-type echo-reply -i $INT_IF -j ACCEPT +## from Peer LAN +$IPC -A input -p icmp -s $ANY -d $MY_INT --icmp-type echo-request -i $IPSEC_IF -j ACCEPT +$IPC -A output -p icmp -s $MY_INT -d $ANY --icmp-type echo-reply -i $IPSEC_IF -j ACCEPT + +# SSH +## from SSH_PEER_HOST +$IPC -A input -p tcp -s $SSH_PEER_HOST -d $MY_EXT 22 -i $EXT_IF -j ACCEPT +$IPC -A output -p tcp \! -y -s $MY_EXT 22 -d $SSH_PEER_HOST -i $EXT_IF -j ACCEPT +## to SSH_PEER_HOST +$IPC -A input -p tcp \! -y -s $SSH_PEER_HOST 22 -d $MY_EXT -i $EXT_IF -j ACCEPT +$IPC -A output -p tcp -s $MY_EXT -d $SSH_PEER_HOST 22 -i $EXT_IF -j ACCEPT +## from PEER +$IPC -A input -p tcp -s $PEER_EXT -d $MY_EXT 22 -i $EXT_IF -j ACCEPT +$IPC -A output -p tcp \! -y -s $MY_EXT 22 -d $PEER_EXT -i $EXT_IF -j ACCEPT +## to PEER +$IPC -A input -p tcp \! -y -s $PEER_EXT 22 -d $MY_EXT -i $EXT_IF -j ACCEPT +$IPC -A output -p tcp -s $MY_EXT -d $PEER_EXT 22 -i $EXT_IF -j ACCEPT + +# ipxtunnel +$IPC -A input -p udp -s $PEER_INT 2005 -d $MY_INT 2005 -i $IPSEC_IF -j ACCEPT +$IPC -A output -p udp -s $MY_INT 2005 -d $PEER_INT 2005 -i $IPSEC_IF -j ACCEPT + +---------------- end of rc.firewall ---------------------- + +To understand this we need to look on this scheme: + + ++-----------------------<----------------------------+ + || ipsec0 | + \/ | + eth0 +--------+ /---------/ yes /---------/ yes +-----------------------+ +------>| INPUT |-->/ ?local? /----->/ ?IPsec? /----->| decrypt & decapsulate | + eth1 +--------+ /---------/ /---------/ +-----------------------+ + || no || no + \/ \/ + +----------+ +---------+ +-------+ + | routing | | local | | local | + | decision | | deliver | | send | + +----------+ +---------+ +-------+ + || || + \/ \/ + +---------+ +----------+ + | forward | | routing | + +---------+ | decision | + || +----------+ + || || + ++----------------<-----------------++ + || + \/ + +--------+ eth0 + | OUTPUT | eth1 + +--------+ ipsec0 + || + \/ + /---------/ yes +-----------------------+ + / ?IPsec? /----->| encrypt & encapsulate | + /---------/ +-----------------------+ + || no || + || || + || \/ eth0, eth1 + ++-----------------------++--------------> + +This explain how a packet traverse TCP/IP stack in IPsec capable kernel. + +FIX ME, please, if there are any errors + +Test the new firewall now. + + +Now about IPX. I tried 3 programs for tunneling IPX: tipxd, SIB and ipxtunnel + +tipxd didn't send packets.. :( +SIB and ipxtunnel worked fine :) +With ipxtunnel there was a little problem. In sources there are an error. + +--------------------- in main.c ------------------------ +< bytes += p.len; +--- +> bytes += len; +-------------------------------------------------------- + +After this FIX everything goes right... + +------------------- /etc/ipxtunnel.conf ---------------- +port 2005 +remote 192.168.101.97 2005 +interface eth1 +--------------- end of /etc/ipxtunnel.conf ------------- + +I use IPX tunnel between .1.1 and .2.10 so we don't need to encrypt nor +authenticate encapsulated IPX packets, it is done with IPsec. + +If you don't wont to use iproute2 to change source IP you need to use SIB +(it is able to bind local address) or establish tunnel between .0.1 and +.0.10 (external IPs, you need to do encryption in the program, but it isn't +strong). + +For now I'm using ipxtunnel. + +I think that's all for the moment. If there are any error, please e-mail me: +poltorak@df.ru . It would be cool if someone puts the scheme of TCP/IP in +kernel and firewall example on FreeS/WAN's manual pages. + +PoltoS +</pre> + +</body> +</html>
\ No newline at end of file diff --git a/doc/src/web.html b/doc/src/web.html new file mode 100644 index 000000000..19df6ffa6 --- /dev/null +++ b/doc/src/web.html @@ -0,0 +1,905 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html"> + <title>FreeS/WAN web links</title> + <meta name="keywords" + content="Linux, IPsec, VPN, security, FreeSWAN, links, web"> + <!-- + + Written by Sandy Harris for the Linux FreeS/WAN project + Freely distributable under the GNU General Public License + + More information at www.freeswan.org + Feedback to users@lists.freeswan.org + + CVS information: + RCS ID: $Id: web.html,v 1.1 2004/03/15 20:35:24 as Exp $ + Last changed: $Date: 2004/03/15 20:35:24 $ + Revision number: $Revision: 1.1 $ + + CVS revision numbers do not correspond to FreeS/WAN release numbers. + --> +</head> + +<body> +<h1><a name="weblink">Web links</a></h1> + +<h2><a name="freeswan">The Linux FreeS/WAN Project</a></h2> + +<p>The main project web site is <a +href="http://www.freeswan.org/">www.freeswan.org</a>.</p> + +<p>Links to other project-related <a href="intro.html#sites">sites</a> are +provided in our introduction section.</p> + +<h3><a name="patch">Add-ons and patches for FreeS/WAN</a></h3> + +<p>Some user-contributed patches have been integrated into the FreeS/WAN +distribution. For a variety of reasons, those listed below have not.</p> + +<p>Note that not all patches are a good idea.</p> +<ul> + <li>There are a number of "features" of IPsec which we do not implement + because they reduce security. See this <a + href="compat.html#dropped">discussion</a>. We do not recommend using + patches that implement these. One example is aggressive mode.</li> + <li>We do not recommend adding "features" of any sort unless they are + clearly necessary, or at least have clear benefits. For example, + FreeS/WAN would not become more secure if it offerred a choice of 14 + ciphers. If even one was flawed, it would certainly become less secure + for anyone using that cipher. Even with 14 wonderful ciphers, it would be + harder to maintain and administer, hence more vulnerable to various human + errors.</li> +</ul> + +<p>This is not to say that patches are necessarily bad, only that using them +requires some deliberation. For example, there might be perfectly good +reasons to add a specific cipher in your application: perhaps GOST to comply +with government standards in Eastern Europe, or AES for performance +benefits.</p> + +<h4>Current patches</h4> + +<p>Patches believed current::</p> +<ul> + <li>patches for <a href="http://www.strongsec.com/freeswan/">X.509 + certificate support</a>, also available from a <a + href="http://www.twi.ch/~sna/strongsec/freeswan/">mirror site</a></li> + <li>patches to add <a href="http://www.irrigacion.gov.ar/juanjo/ipsec">AES + and other ciphers</a>. There is preliminary data indicating AES gives a + substantial <a href="performance.html#perf.more">performance + gain</a>.</li> +</ul> + +<p>There is also one add-on that takes the form of a modified FreeS/WAN +distribution, rather than just patches to the standard distribution:</p> +<ul> + <li><a href="http://www.ipv6.iabg.de/downloadframe/index.html">IPv6 + support</a></li> +</ul> + +<p>Before using any of the above,, check the <a href="mail.html">mailing +lists</a> for news of newer versions and to see whether they have been +incorporated into more recent versions of FreeS/WAN.</p> + +<h4>Older patches</h4> +<ul> + <li><a href="http://sources.colubris.com/en/projects/FreeSWAN/">hardware + acceleration</a></li> + <li>a <a href="http://tzukanov.narod.ru/">series</a> of patches that + <ul> + <li>provide GOST, a Russian gov't. standard cipher, in MMX + assembler</li> + <li>add GOST to OpenSSL</li> + <li>add GOST to the International kernel patch</li> + <li>let FreeS/WAN use International kernel patch ciphers</li> + </ul> + </li> + <li>Neil Dunbar's patches for <a + href="ftp://hplose.hpl.hp.com/pub/nd/pluto-openssl.tar.gz">certificate + support</a>, using code from <a href="http://www.openssl.org">Open + SSL</a>.</li> + <li>Luc Lanthier's <a + href="ftp://ftp.netwinder.org/users/f/firesoul/">patches</a> for <a + href="glossary.html#PKIX">PKIX</a> support.</li> + <li><a href="ftp://ftp.heise.de/pub/ct/listings/9916-180.tgz">patches</a> + to add <a href="glossary.html#blowfish">Blowfish</a>, <a + href="glossary.html#IDEA">IDEA</a> and <a + href="glossary.html#CAST128">CAST-128</a> to FreeS/WAN</li> + <li>patches for FreeS/WAN 1.3, Pluto support for <a + href="http://alcatraz.webcriminals.com/~bastiaan/ipsec/">external + authentication</a>, for example with a smartcard or SKEYID.</li> + <li><a href="http://www.zengl.net/freeswan/download/">patches and + utilities</a> for using FreeS/WAN with PGPnet</li> + <li><a + href="http://www.freelith.com/lithworks/crypto/freeswan_patch.htm">Blowfish + encryption and Tiger hash</a></li> + <li><a + href="http://www.cendio.se/~bellman/aggressive-pluto.snap.tar.gz">patches</a> + for aggressive mode support</li> +</ul> + +<p>These patches are for older versions of FreeS/WAN and will likely not work +with the current version. Older versions of FreeS/WAN may be available on +some of the <a href="intro.html#sites">distribution sites</a>, but we +recommend using the current release.</p> + +<h4><a name="VPN.masq">VPN masquerade patches</a></h4> + +<p>Finally, there are some patches to other code that may be useful with +FreeS/WAN:</p> +<ul> + <li>a <a + href="ftp://ftp.rubyriver.com/pub/jhardin/masquerade/ip_masq_vpn.html">patch</a> + to make IPsec, PPTP and SSH VPNs work through a Linux firewall with <a + href="glossary.html#masq">IP masquerade</a>.</li> + <li><a href="http://www.linuxdoc.org/HOWTO/VPN-Masquerade-HOWTO.html">Linux + VPN Masquerade HOWTO</a></li> +</ul> + +<p>Note that this is not required if the same machine does IPsec and +masquerading, only if you want a to locate your IPsec gateway on a +masqueraded network. See our <a href="firewall.html#NAT">firewalls</a> +document for discussion of why this is problematic.</p> + +<p>At last report, this patch could not co-exist with FreeS/WAN on the same +machine.</p> + +<h3><a name="dist">Distributions including FreeS/WAN</a></h3> + +<p>The introductory section of our document set lists several <a +href="intro.html#distwith">Linux distributions</a> which include +FreeS/WAN.</p> + +<h3><a name="used">Things FreeS/WAN uses or could use</a></h3> +<ul> + <li><a href="http://openpgp.net/random">/dev/random</a> support page, + discussion of and code for the Linux <a + href="glossary.html#random">random number driver</a>. Out-of-date when we + last checked (January 2000), but still useful.</li> + <li>other programs related to random numbers: + <ul> + <li><a href="http://www.mindrot.org/audio-entropyd.html">audio entropy + daemon</a> to gather noise from a sound card and feed it into + /dev/random</li> + <li>an <a href="http://www.lothar.com/tech/crypto/">entropy-gathering + daemon</a></li> + <li>a driver for the random number generator in recent <a + href="http://sourceforge.net/projects/gkernel/">Intel chipsets</a>. + This driver is included as standard in 2.4 kernels.</li> + </ul> + </li> + <li>a Linux <a href="http://www.marko.net/l2tp/">L2TP Daemon</a> which + might be useful for communicating with Windows 2000 which builds L2TP + tunnels over its IPsec connections</li> + <li>to use opportunistic encryption, you need a recent version of <a + href="glossary.html#BIND">BIND</a>. You can get one from the <a + href="http://www.isc.org">Internet Software Consortium</a> who maintain + BIND.</li> +</ul> + +<h3><a name="alternatives">Other approaches to VPNs for Linux</a></h3> +<ul> + <li>other Linux <a href="#linuxipsec">IPsec implementations</a></li> + <li><a href="http://www.tik.ee.ethz.ch/~skip/">ENskip</a>, a free + implementation of Sun's <a href="glossary.html#SKIP">SKIP</a> + protocol</li> + <li><a href="http://sunsite.auc.dk/vpnd/">vpnd</a>, a non-IPsec VPN daemon + for Linux which creates tunnels using <a + href="glossary.html#Blowfish">Blowfish</a> encryption</li> + <li><a href="http://www.winton.org.uk/zebedee/">Zebedee</a>, a simple GPLd + tunnel-building program with Linux and Win32 versions. The name is from + <strong>Z</strong>lib compression, <strong>B</strong>lowfish encryption + and <strong>D</strong>iffie-Hellman key exchange.</li> + <li>There are at least two PPTP implementations for Linux + <ul> + <li>Moreton Bay's <a + href="http://www.moretonbay.com/vpn/pptp.html">PoPToP</a></li> + <li><a + href="http://cag.lcs.mit.edu/~cananian/Projects/PPTP/">PPTP-Linux</a></li> + </ul> + </li> + <li><a href="http://sites.inka.de/sites/bigred/devel/cipe.html">CIPE</a> + (crypto IP encapsulation) project, using their own lightweight protocol + to encrypt between routers</li> + <li><a href="http://tinc.nl.linux.org/">tinc</a>, a VPN Daemon</li> +</ul> + +<p>There is a list of <a +href="http://www.securityportal.com/lskb/10000000/kben10000005.html">Linux +VPN</a> software in the <a +href="http://www.securityportal.com/lskb/kben00000001.html">Linux Security +Knowledge Base</a>.</p> + +<h2><a name="ipsec.link">The IPsec Protocols</a></h2> + +<h3><a name="general">General IPsec or VPN information</a></h3> +<ul> + <li>The <a href="http://www.vpnc.org">VPN Consortium</a> is a group for + vendors of IPsec products. Among other things, they have a good + collection of <a href="http://www.vpnc.org/white-papers.html">IPsec white + papers</a>.</li> + <li>A VPN mailing list with a <a + href="http://kubarb.phsx.ukans.edu/~tbird/vpn.html">home page</a>, a FAQ, + some product comparisons, and many links.</li> + <li><a href="http://www.opus1.com/vpn/index.html">VPN pointer page</a></li> + <li>a <a href="http://www.epm.ornl.gov/~dunigan/vpn.html">collection</a> of + VPN links, and some explanation</li> +</ul> + +<h3><a name="overview">IPsec overview documents or slide sets</a></h3> +<ul> + <li>the FreeS/WAN <a href="ipsec.html">document section</a> on these + protocols</li> +</ul> + +<h3><a name="otherlang">IPsec information in languages other than +English</a></h3> +<ul> + <li><a + href="http://www.imib.med.tu-dresden.de/imib/Internet/Literatur/ipsec-docu.html">German</a></li> + <li><a href="http://www.kame.net/index-j.html">Japanese</a></li> + <li>Feczak Szabolcs' thesis in <a + href="http://feczo.koli.kando.hu/vpn/">Hungarian</a></li> + <li>Davide Cerri's thesis and some presentation slides <a + href="http://www.linux.it/~davide/doc/">Italian</a></li> +</ul> + +<h3><a name="RFCs1">RFCs and other reference documents</a></h3> +<ul> + <li><a href="rfc.html">Our document</a> listing the RFCs relevant to Linux + FreeS/WAN and giving various ways of obtaining both RFCs and Internet + Drafts.</li> + <li><a href="http://www.vpnc.org/vpn-standards.html">VPN Standards</a> page + maintained by <a href="glossary.html#VPNC">VPNC</a>. This covers both + RFCs and Drafts, and classifies them in a fairly helpful way.</li> + <li><a href="http://www.rfc-editor.org">RFC archive</a></li> + <li><a href="http://www.ietf.org/ids.by.wg/ipsec.html">Internet Drafts</a> + related to IPsec</li> + <li>US government <a href="http://www.itl.nist.gov/div897/pubs"> site</a> + with their <a href="glossary.html#FIPS">FIPS</a> standards</li> + <li>Archives of the ipsec@tis.com mailing list where discussion of drafts + takes place. + <ul> + <li><a href="http://www.sandelman.ottawa.on.ca/ipsec">Eastern + Canada</a></li> + <li><a href="http://www.vpnc.org/ietf-ipsec">California</a>.</li> + </ul> + </li> +</ul> + +<h3><a name="analysis">Analysis and critiques of IPsec protocols</a></h3> +<ul> + <li>Counterpane's <a + href="http://www.counterpane.com/ipsec.pdf">evaluation</a> of the + protocols</li> + <li>Simpson's <a + href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/1999/06/msg00319.html">IKE + Considered Dangerous</a> paper. Note that this is a link to an archive of + our mailing list. There are several replies in addition to the paper + itself.</li> + <li>Fate Labs <a href="http://www.fatelabs.com/loki-vpn.pdf">Virual Private + Problems: the Broken Dream</a></li> + <li>Catherine Meadows' paper <cite>Analysis of the Internet Key Exchange + Protocol Using the NRL Protocol Analyzer</cite>, in <a + href="http://chacs.nrl.navy.mil/publications/CHACS/1999/1999meadows-IEEE99.pdf">PDF</a> + or <a + href="http://chacs.nrl.navy.mil/publications/CHACS/1999/1999meadows-IEEE99.ps">Postscript</a>.</li> + <li>Perlman and Kaufmnan + <ul> + <li><a + href="http://snoopy.seas.smu.edu/ee8392_summer01/week7/perlman2.pdf">Key + Exchange in IPsec</a></li> + <li>a newer <a + href="http://sec.femto.org/wetice-2001/papers/radia-paper.pdf">PDF + paper</a>, <cite>Analysis of the IPsec Key Exchange + Standard</cite>.</li> + </ul> + </li> + <li>Bellovin's <a + href="http://www.research.att.com/~smb/papers/index.html">papers</a> page + including his: + <ul> + <li><cite>Security Problems in the TCP/IP Protocol Suite</cite> + (1989)</li> + <li><cite>Problem Areas for the IP Security Protocols</cite> (1996)</li> + <li><cite>Probable Plaintext Cryptanalysis of the IP Security + Protocols</cite> (1997)</li> + </ul> + </li> + <li>An <a href="http://www.lounge.org/ike_doi_errata.html">errata list</a> + for the IPsec RFCs.</li> +</ul> + +<h3><a name="IP.background">Background information on IP</a></h3> +<ul> + <li>An <a href="http://ipprimer.windsorcs.com/">IP tutorial</a> that seems + to be written mainly for Netware or Microsoft LAN admins entering a new + world</li> + <li><a href="http://www.iana.org">IANA</a>, Internet Assigned Numbers + Authority</li> + <li><a href="http://public.pacbell.net/dedicated/cidr.html">CIDR</a>, + Classless Inter-Domain Routing</li> + <li>Also see our <a href="biblio.html">bibliography</a></li> +</ul> + +<h2><a name="implement">IPsec Implementations</a></h2> + +<h3><a name="linuxprod">Linux products</a></h3> + +<p>Vendors using FreeS/WAN in turnkey firewall or VPN products are listed in +our <a href="intro.html#turnkey">introduction</a>.</p> + +<p>Other vendors have Linux IPsec products which, as far as we know, do not +use FreeS/WAN</p> +<ul> + <li><a href="http://www.redcreek.com/products/shareware.html">Redcreek</a> + provide an open source Linux driver for their PCI hardware VPN card. This + card has a 100 Mbit Ethernet port, an Intel 960 CPU plus more specialised + crypto chips, and claimed encryption performance of 45 Mbit/sec. The PC + sees it as an Ethernet board.</li> + <li><a href="http://linuxtoday.com/stories/8428.html?nn">Paktronix</a> + offer a Linux-based VPN with hardware encryption</li> + <li><a href="http://www.watchguard.com/">Watchguard</a> use Linux in their + Firebox product.</li> + <li><a href="http://www.entrust.com">Entrust</a> offer a developers' + toolkit for using their <a href="glossary.html#PKI">PKI</a> for IPsec + authentication</li> + <li>According to a report on our mailing list, <a + href="http://www.axent.com">Axent</a> have a Linux version of their + product.</li> +</ul> + +<h3><a name="router">IPsec in router products</a></h3> + +<p>All the major router vendors support IPsec, at least in some models.</p> +<ul> + <li><a href="http://www.cisco.com/warp/public/707/16.html">Cisco</a> IPsec + information</li> + <li>Ascend, now part of <a href="http://www.lucent.com/">Lucent</a>, have + some IPsec-based products</li> + <li><a href="http://www.nortelnetworks.com/">Bay Networks</a>, now part of + Nortel, use IPsec in their Contivity switch product line</li> + <li><a href="http://www.3com.com/products/enterprise.html">3Com</a> have a + number of VPN products, some using IPsec</li> +</ul> + +<h3><a name="fw.web">IPsec in firewall products</a></h3> + +<p>Many firewall vendors offer IPsec, either as a standard part of their +product, or an optional extra. A few we know about are:</p> +<ul> + <li><a href="http://www.borderware.com/">Borderware</a></li> + <li><a href="http://www.ashleylaurent.com/vpn/ipsec_vpn.htm">Ashley + Laurent</a></li> + <li><a href="http://www.watchguard.com">Watchguard</a></li> + <li><a href="http://www.fx.dk/firewall/ipsec.html">Injoy</a> for OS/2</li> +</ul> + +<p>Vendors using FreeS/WAN in turnkey firewall products are listed in our <a +href="intro.html#turnkey">introduction</a>.</p> + +<h3><a name="ipsecos">Operating systems with IPsec support</a></h3> + +<p>All the major open source operating systems support IPsec. See below for +details on <a href="#BSD">BSD-derived</a> Unix variants.</p> + +<p>Among commercial OS vendors, IPsec players include:</p> +<ul> + <li><a + href="http://msdn.microsoft.com/isapi/msdnlib.idc?theURL=/library/backgrnd/html/msdn_ip_security.htm">Microsoft</a> + have put IPsec in their Windows 2000 and XP products</li> + <li><a + href="http://www.s390.ibm.com/stories/1999/os390v2r8_pr.html">IBM</a> + announce a release of OS390 with IPsec support via a crypto + co-processor</li> + <li><a + href="http://www.sun.com/solaris/ds/ds-security/ds-security.pdf">Sun</a> + include IPsec in Solaris 8</li> + <li><a + href="http://www.hp.com/security/products/extranet-security.html">Hewlett + Packard</a> offer IPsec for their Unix machines</li> + <li>Certicom have IPsec available for the <a + href="http://www.certicom.com/products/movian/movianvpn_tech.html">Palm</a>.</li> + <li>There were reports before the release that Apple's Mac OS X would have + IPsec support built in, but it did not seem to be there when we last + checked. If you find, it please let us know via the <a + href="mail.html">mailing list</a>.</li> +</ul> + +<h3>IPsec on network cards</h3> + +<p>Network cards with built-in IPsec acceleration are available from at least +Intel, 3Com and Redcreek.</p> + +<h3><a name="opensource">Open source IPsec implementations</a></h3> + +<h4><a name="linuxipsec">Other Linux IPsec implementations</a></h4> + +<p>We like to think of FreeS/WAN as <em>the</em> Linux IPsec implementation, +but it is not the only one. Others we know of are:</p> +<ul> + <li><a href="http://www.enst.fr/~beyssac/pipsec/">pipsecd</a>, a + lightweight implementation of IPsec for Linux. Does not require kernel + recompilation.</li> + <li>Petr Novak's <a href="ftp://ftp.eunet.cz/icz/ipnsec/">ipnsec</a>, based + on the OpenBSD IPsec code and using <a + href="glossary.html#photuris">Photuris</a> for key management</li> + <li>A now defunct project at <a + href="http://www.cs.arizona.edu/security/hpcc-blue/linux.html">U of + Arizona</a> (export controlled)</li> + <li><a href="http://snad.ncsl.nist.gov/cerberus">NIST Cerebus</a> (export + controlled)</li> +</ul> + +<h4><a name="BSD">IPsec for BSD Unix</a></h4> +<ul> + <li><a href="http://www.kame.net/project-overview.html">KAME</a>, several + large Japanese companies co-operating on IPv6 and IPsec</li> + <li><a href="http://web.mit.edu/network/isakmp">US Naval Research Lab</a> + implementation of IPv6 and of IPsec for IPv4 (export controlled)</li> + <li><a href="http://www.openbsd.org">OpenBSD</a> includes IPsec as a + standard part of the distribution</li> + <li><a href="http://www.r4k.net/ipsec">IPsec for FreeBSD</a></li> + <li>a <a href="http://www.netbsd.org/Documentation/network/ipsec/">FAQ</a> + on NetBSD's IPsec implementation</li> +</ul> + +<h4><a name="misc">IPsec for other systems</a></h4> +<ul> + <li><a href="http://www.tcm.hut.fi/Tutkimus/IPSEC/">Helsinki U of + Technolgy</a> have implemented IPsec for Solaris, Java and Macintosh</li> +</ul> + +<h3><a name="interop.web">Interoperability</a></h3> + +<p>The IPsec protocols are designed so that different implementations should +be able to work together. As they say "the devil is in the details". IPsec +has a lot of details, but considerable success has been achieved.</p> + +<h4><a name="result">Interoperability results</a></h4> + +<p>Linux FreeS/WAN has been tested for interoperability with many other IPsec +implementations. Results to date are in our <a +href="interop.html">interoperability</a> section.</p> + +<p>Various other sites have information on interoperability between various +IPsec implementations:</p> +<ul> + <li><a href="http://www.opus1.com/vpn/atl99display.html">interop + results</a> from a bakeoff in Atlanta, September 1999.</li> + <li>a French company, HSC's, <a + href="http://www.hsc.fr/ressources/presentations/ipsec99/index.html.en">interoperability</a> + test data covers FreeS/WAN, Open BSD, KAME, Linux pipsecd, Checkpoint, + Red Creek Ravlin, and Cisco IOS</li> + <li><a href="http://www.icsa.net/">ICSA</a> offer certification programs + for various security-related products. See their list of <a + href="http://www.icsa.net/html/communities/ipsec/certification/certified_products/index.shtml"> + certified IPsec</a> products. Linux FreeS/WAN is not currently on that + list, but several products with which we interoperate are.</li> + <li>VPNC have a page on why they are not yet doing <a + href="http://www.vpnc.org/interop.html">interoperability</a> testing and + a page on the <a href="http://www.vpnc.org/conformance.html">spec + conformance</a> testing that they are doing</li> + <li>a <a href="http://www.commweb.com/article/COM20000912S0009">review</a> + comparing a dozen commercial IPsec implemetations. Unfortunately, the + reviewers did not look at Open Source implementations such as FreeS/WAN + or OpenBSD.</li> + <li><a + href="http://www.tanu.org/~sakane/doc/public/report-ike-interop0007.html">results</a> + from interoperability tests at a conference. FreeS/WAN was not tested + there.</li> + <li>test results from the <a + href="http://www.hsc.fr/ressources/veille/ipsec/ipsec2000/">IPSEC + 2000</a> conference</li> +</ul> + +<h4><a name="test1">Interoperability test sites</a></h4> +<ul> + <li><a href="http://www.tahi.org/">TAHI</a>, a Japanese IPv6 testing + project with free IPsec validation software</li> + <li><a href="http://ipsec-wit.antd.nist.gov">National Institute of + Standards and Technology</a></li> + <li><a href="http://isakmp-test.ssh.fi/">SSH Communications + Security</a></li> +</ul> + +<h2><a name="linux.link">Linux links</a></h2> + +<h3><a name="linux.basic">Basic and tutorial Linux information</a></h3> +<ul> + <li>Linux <a + href="http://linuxcentral.com/linux/LDP/LDP/gs/gs.html">Getting + Started</a> HOWTO document</li> + <li>A getting started guide from the <a + href="http://darkwing.uoregon.edu/~cchome/linuxgettingstarted.html">U of + Oregon</a></li> + <li>A large <a href="http://www.herring.org/techie.html">link + collection</a> which includes a lot of introductory and tutorial material + on Unix, Linux, the net, . . .</li> +</ul> + +<h3><a name="general">General Linux sites</a></h3> +<ul> + <li><a href="http://www.freshmeat.net">Freshmeat</a> Linux news</li> + <li><a href="http://slashdot.org">Slashdot</a> "News for Nerds"</li> + <li><a href="http://www.linux.org">Linux Online</a></li> + <li><a href="http://www.linuxhq.com">Linux HQ</a></li> + <li><a href="http://www.tux.org">tux.org</a></li> +</ul> + +<h3><a name="docs.ldp">Documentation</a></h3> + +<p>Nearly any Linux documentation you are likely to want can be found at the +<a href="http://metalab.unc.edu/LDP">Linux Documentation Project</a> or +LDP.</p> +<ul> + <li><a href="http://metalab.unc.edu/LDP/HOWTO/META-FAQ.html">Meta-FAQ</a> + guide to Linux information sources</li> + <li>The LDP's HowTo documents are a standard Linux reference. See this <a + href="http://www.linuxdoc.org/docs.html#howto">list</a>. Documents there + most relevant to a FreeS/WAN gateway are: + <ul> + <li><a href="http://metalab.unc.edu/LDP/HOWTO/Kernel-HOWTO.html">Kernel + HOWTO</a></li> + <li><a + href="http://metalab.unc.edu/LDP/HOWTO/Networking-Overview-HOWTO.html">Networking + Overview HOWTO</a></li> + <li><a + href="http://metalab.unc.edu/LDP/HOWTO/Security-HOWTO.html">Security + HOWTO</a></li> + </ul> + </li> + <li>The LDP do a series of Guides, book-sized publications with more detail + (and often more "why do it this way?") than the HowTos. See this <a + href="http://www.linuxdoc.org/guides.html">list</a>. Documents there most + relevant to a FreeS/WAN gateway are: + <ul> + <li><a href="http://www.tml.hut.fi/~viu/linux/sag/">System + Administrator's Guide</a></li> + <li><a href="http://www.linuxdoc.org/LDP/nag2/index.html">Network + Adminstrator's Guide</a></li> + <li><a href="http://www.seifried.org/lasg/">Linux Administrator's + Security Guide</a></li> + </ul> + </li> +</ul> + +<p>You may not need to go to the LDP to get this material. Most Linux +distributions include the HowTos on their CDs and several include the Guides +as well. Also, most of the Guides and some collections of HowTos are +available in book form from various publishers.</p> + +<p>Much of the LDP material is also available in languages other than +English. See this <a href="http://www.linuxdoc.org/links/nenglish.html">LDP +page</a>.</p> + +<h3><a name="advroute.web">Advanced routing</a></h3> + +<p>The Linux IP stack has some new features in 2.4 kernels. Some HowTos have +been written:</p> +<ul> + <li>several HowTos for the <a + href="http://netfilter.samba.org/unreliable-guides/">netfilter</a> + firewall code in newer kernels</li> + <li><a + href="http://www.ds9a.nl/2.4Networking/HOWTO//cvs/2.4routing/output/2.4networking.html">2.4 + networking</a> HowTo</li> + <li><a + href="http://www.ds9a.nl/2.4Networking/HOWTO//cvs/2.4routing/output/2.4routing.html">2.4 + routing</a> HowTo</li> +</ul> + +<h3><a name="linsec">Security for Linux</a></h3> + +<p>See also the <a href="#docs.ldp">LDP material</a> above.</p> +<ul> + <li><a + href="http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#trinityos">Trinity + OS guide to setting up Linux</a></li> + <li><a href="http://www.deter.com/unix">Unix security</a> page</li> + <li><a href="http://linux01.gwdg.de/~alatham/">PPDD</a> encrypting + filesystem</li> + <li><a href="http://EncryptionHOWTO.sourceforge.net/">Linux Encryption + HowTo</a> (outdated when last checked, had an Oct 2000 revision date in + March 2002)</li> +</ul> + +<h3><a name="firewall.linux">Linux firewalls</a></h3> + +<p>Our <a href="firewall.html">FreeS/WAN and firewalls</a> document includes +links to several sets of <a href="firewall.html#examplefw">scripts</a> known +to work with FreeS/WAN.</p> + +<p>Other information sources:</p> +<ul> + <li><a href="http://ipmasq.cjb.net/">IP Masquerade resource page</a></li> + <li><a href="http://netfilter.samba.org/unreliable-guides/">netfilter</a> + firewall code in 2.4 kernels</li> + <li>Our list of general <a href="#firewall.web">firewall references</a> on + the web</li> + <li><a href="http://users.dhp.com/~whisper/mason/">Mason</a>, a tool for + automatically configuring Linux firewalls</li> + <li>the web cache software <a href="http://www.squid-cache.org/">squid</a> + and <a href="http://www.squidguard.org/">squidguard</a> which turns Squid + into a filtering web proxy</li> +</ul> + +<h3><a name="linux.misc">Miscellaneous Linux information</a></h3> +<ul> + <li><a href="http://lwn.net/current/dists.php3">Linux distribution + vendors</a></li> + <li><a href="http://www.linux.org/groups/">Linux User Groups</a></li> +</ul> + +<h2><a name="crypto.link">Crypto and security links</a></h2> + +<h3><a name="security">Crypto and security resources</a></h3> + +<h4><a name="std.links">The standard link collections</a></h4> + +<p>Two enormous collections of links, each the standard reference in its +area:</p> +<dl> + <dt>Gene Spafford's <a + href="http://www.cerias.purdue.edu/coast/hotlist/">COAST hotlist</a></dt> + <dd>Computer and network security.</dd> + <dt>Peter Gutmann's <a + href="http://www.cs.auckland.ac.nz/~pgut001/links.html">Encryption and + Security-related Resources</a></dt> + <dd>Cryptography.</dd> +</dl> + +<h4><a name="FAQ">Frequently Asked Question (FAQ) documents</a></h4> +<ul> + <li><a href="http://www.faqs.org/faqs/cryptography-faq/">Cryptography + FAQ</a></li> + <li><a href="http://www.interhack.net/pubs/fwfaq">Firewall FAQ</a></li> + <li><a href="http://www.whitefang.com/sup/secure-faq.html">Secure Unix + Programming FAQ</a></li> + <li>FAQs for specific programs are listed in the <a href="#tools">tools</a> + section below.</li> +</ul> + +<h4><a name="cryptover">Tutorials</a></h4> +<ul> + <li>Gary Kessler's <a + href="http://www.garykessler.net/library/crypto.html">Overview of + Cryptography</a></li> + <li>Terry Ritter's <a + href="http://www.ciphersbyritter.com/LEARNING.HTM">introduction</a></li> + <li>Peter Gutman's <a + href="http://www.cs.auckland.ac.nz/~pgut001/tutorial/index.html">cryptography</a> + tutorial (500 slides in PDF format)</li> + <li>Amir Herzberg of IBM's sildes for his course <a + href="http://www.hrl.il.ibm.com/mpay/course.html">Introduction to + Cryptography and Electronic Commerce</a></li> + <li>the <a href="http://www.gnupg.org/gph/en/manual/c173.html">concepts + section</a> of the <a href="glossary.html#GPG">GNU Privacy Guard</a> + documentation</li> + <li>Bruce Schneier's self-study <a + href="http://www.counterpane.com/self-study.html">cryptanalysis</a> + course</li> +</ul> + +<p>See also the <a href="#interesting">interesting papers</a> section +below.</p> + +<h4><a name="standards">Crypto and security standards</a></h4> +<ul> + <li><a href="http://csrc.nist.gov/cc">Common Criteria</a>, new + international computer and network security standards to replace the + "Rainbow" series</li> + <li>AES <a href="http://csrc.nist.gov/encryption/aes/aes_home.htm"> + Advanced Encryption Standard </a> which will replace DES</li> + <li><a href="http://grouper.ieee.org/groups/1363">IEEE P-1363 public key + standard</a></li> + <li>our collection of links for the <a href="#ipsec.link">IPsec</a> + standards</li> + <li>history of <a + href="http://www.visi.com/crypto/evalhist/index.html">formal + evaluation</a> of security policies and implementation</li> +</ul> + +<h4><a name="quotes">Crypto quotes</a></h4> + +<p>There are several collections of cryptographic quotes on the net:</p> +<ul> + <li><a href="http://www.eff.org/pub/EFF/quotes.eff">the EFF</a></li> + <li><a href="http://www.samsimpson.com/cquotes.php">Sam Simpson</a></li> + <li><a href="http://www.amk.ca/quotations/cryptography/page-1.html">AM + Kutchling</a></li> +</ul> + +<h3><a name="policy">Cryptography law and policy</a></h3> + +<h4><a name="legal">Surveys of crypto law</a></h4> +<ul> + <li>International survey of <a + href="http://cwis.kub.nl/~FRW/PEOPLE/koops/lawsurvy.htm"> crypto + law</a>.</li> + <li>International survey of <a + href="http://rechten.kub.nl/simone/ds-lawsu.htm"> digital signature + law</a></li> +</ul> + +<h4><a name="oppose">Organisations opposing crypto restrictions</a></h4> +<ul> + <li>The <a href="glossary.html#EFF">EFF</a>'s archives on <a + href="http://www.eff.org/pub/Privacy/">privacy</a> and <a + href="http://www.eff.org/pub/Privacy/ITAR_export/">export + control</a>.</li> + <li><a href="http://www.gilc.org">Global Internet Liberty Campaign</a></li> + <li><a href="http://www.cdt.org/crypto">Center for Democracy and + Technology</a></li> + <li><a href="http://www.privacyinternational.org/">Privacy + International</a>, who give out <a + href="http://www.bigbrotherawards.org/">Big Brother Awards</a> to snoopy + organisations</li> +</ul> + +<h4><a name="other.policy">Other information on crypto policy</a></h4> +<ul> + <li><a href="ftp://ftp.isi.edu/in-notes/rfc1984.txt">RFC 1984</a>, the <a + href="glossary.html#IAB">IAB</a> and <a + href="glossary.html#IESG">IESG</a> Statement on Cryptographic Technology + and the Internet.</li> + <li>John Young's collection of <a href="http://cryptome.org/">documents</a> + of interest to the cryptography, open government and privacy movements, + organized chronologically</li> + <li>AT&T researcher Matt Blaze's Encryption, Privacy and Security <a + href="http://www.crypto.com">Resource Page</a></li> + <li>A good <a href="http://cryptome.org/crypto97-ne.htm">overview</a> of + the issues from Australia.</li> +</ul> + +<p>See also our documentation section on the <a href="politics.html">history +and politics</a> of cryptography.</p> + +<h3><a name="crypto.tech">Cryptography technical information</a></h3> + +<h4><a name="cryptolinks">Collections of crypto links</a></h4> +<ul> + <li><a href="http://www.counterpane.com/hotlist.html">Counterpane</a></li> + <li><a href="http://www.cs.auckland.ac.nz/~pgut001/links.html">Peter + Gutman's links</a></li> + <li><a href="http://www.pca.dfn.de/eng/team/ske/pem-dok.html">PKI + links</a></li> + <li><a href="http://crypto.yashy.com/www/">Robert Guerra's links</a></li> +</ul> + +<h4><a name="papers">Lists of online cryptography papers</a></h4> +<ul> + <li><a href="http://www.counterpane.com/biblio">Counterpane</a></li> + <li><a + href="http://www.cryptography.com/resources/papers">cryptography.com</a></li> + <li><a href="http://www.cryptosoft.com/html/secpub.htm">Cryptosoft</a></li> +</ul> + +<h4><a name="interesting">Particularly interesting papers</a></h4> + +<p>These papers emphasize important issues around the use of cryptography, +and the design and management of secure systems.</p> +<ul> + <li><a href="http://www.counterpane.com/keylength.html">Key length + requirements for security</a></li> + <li><a href="http://www.cl.cam.ac.uk/users/rja14/wcf.html">Why + Cryptosystems Fail</a></li> + <li><a href="http://www.cdt.org/crypto/risks98/">Risks of escrowed + encryption</a></li> + <li><a href="http://www.counterpane.com/pitfalls.html">Security pitfalls in + cryptography</a></li> + <li><a href="http://www.acm.org/classics/sep95">Reflections on Trusting + Trust</a>, Ken Thompson on Trojan horse design</li> + <li><a href="http://www.apache-ssl.org/disclosure.pdf">Security against + Compelled Disclosure</a>, how to maintain privacy in the face of legal or + other coersion</li> +</ul> + +<h3><a name="compsec">Computer and network security</a></h3> + +<h4><a name="seclink">Security links</a></h4> +<ul> + <li><a href="http://www.cs.purdue.edu/coast/hotlist">COAST Hotlist</a></li> + <li>DMOZ open directory project <a + href="http://dmoz.org/Computers/Security/">computer security</a> + links</li> + <li><a href="http://www-cse.ucsd.edu/users/bsy/sec.html">Bennet Yee</a></li> + <li>Mike Fuhr's <a + href="http://www.fuhr.org/~mfuhr/computers/security.html">link + collection</a></li> + <li><a href="http://www.networkintrusion.co.uk/">links</a> with an emphasis + on intrusion detection</li> +</ul> + +<h4><a name="firewall.web">Firewall links</a></h4> +<ul> + <li><a href="http://www.cs.purdue.edu/coast/firewalls">COAST + firewalls</a></li> + <li><a href="http://www.zeuros.co.uk">Firewalls Resource page</a></li> +</ul> + +<h4><a name="vpn">VPN links</a></h4> +<ul> + <li><a href="http://www.vpnc.org">VPN Consortium</a></li> + <li>First VPN's <a href="http://www.firstvpn.com/research/rhome.html">white + paper</a> collection</li> +</ul> + +<h4><a name="tools">Security tools</a></h4> +<ul> + <li>PGP -- mail encryption + <ul> + <li><a href="http://www.pgp.com/">PGP Inc.</a> (part of NAI) for + commercial versions</li> + <li><a href="http://web.mit.edu/network/pgp.html">MIT</a> distributes + the NAI product for non-commercial use</li> + <li><a href="http://www.pgpi.org/">international</a> distribution + site</li> + <li><a href="http://gnupg.org">GNU Privacy Guard (GPG)</a></li> + <li><a href="http://www.dk.pgp.net/pgpnet/pgp-faq/">PGP FAQ</a></li> + </ul> + A message in our mailing list archive has considerable detail on <a + href="http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/12/msg00029.html">available + versions</a> of PGP and on IPsec support in them. + <p><strong>Note:</strong> A fairly nasty bug exists in all commercial PGP + versions from 5.5 through 6.5.3. If you have one of those, + <strong>upgrade now</strong>.</p> + </li> + <li>SSH -- secure remote login + <ul> + <li><a href="http://www.ssh.fi">SSH Communications Security</a>, for + the original software. It is free for trial, academic and + non-commercial use.</li> + <li><a href="http://www.openssh.com/">Open SSH</a>, the Open BSD team's + free replacement</li> + <li><a href="http://www.freessh.org/">freessh.org</a>, links to free + implementations for many systems</li> + <li><a href="http://www.uni-karlsruhe.de/~ig25/ssh-faq">SSH FAQ</a></li> + <li><a + href="http://www.chiark.greenend.org.uk/~sgtatham/putty/">Putty</a>, + an SSH client for Windows</li> + </ul> + </li> + <li>Tripwire saves message digests of your system files. Re-calculate the + digests and compare to saved values to detect any file changes. There are + several versions available: + <ul> + <li><a href="http://www.tripwiresecurity.com/">commercial + version</a></li> + <li><a href="http://www.tripwire.org/">Open Source</a></li> + </ul> + </li> + <li><a href="http://www.snort.org">Snort</a> and <a + href="http://www.lids.org">LIDS</a> are intrusion detection system for + Linux</li> + <li><a href="http://www.fish.com/~zen/satan/satan.html">SATAN</a> System + Administrators Tool for Analysing Networks</li> + <li><a href="http://www.insecure.org/nmap/">NMAP</a> Network Mapper</li> + <li><a href="ftp://ftp.porcupine.org/pub/security/index.html">Wietse + Venema's page</a> with various tools</li> + <li><a href="http://ita.ee.lbl.gov/index.html">Internet Traffic + Archive</a>, various tools to analyze network traffic, mostly scripts to + organise and format tcpdump(8) output for specific purposes</li> + <li><a name="ssmail">ssmail -- sendmail patched to do</a> <a + href="glossary.html#carpediem">opportunistic encryption</a> + <ul> + <li><a href="http://www.home.aone.net.au/qualcomm/">web page</a> with + links to code and to a Usenix paper describing it, in PDF</li> + </ul> + </li> + <li><a href="http://www.openca.org/">Open CA</a> project to develop a + freely distributed <a href="glossary.html#CA">Certification Authority</a> + for building a open <a href="glossary.html#PKI">Public Key + Infrastructure</a>.</li> +</ul> + +<h3><a name="people">Links to home pages</a></h3> + +<p>David Wagner at Berkeley provides a set of links to <a +href="http://www.cs.berkeley.edu/~daw/people/crypto.html">home pages</a> of +cryptographers, cypherpunks and computer security people.</p> +</body> +</html> |