From aa0f5b38aec14428b4b80e06f90ff781f8bca5f1 Mon Sep 17 00:00:00 2001 From: Rene Mayrhofer Date: Mon, 22 May 2006 05:12:18 +0000 Subject: Import initial strongswan 2.7.0 version into SVN. --- doc/quickstart.html | 323 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 323 insertions(+) create mode 100644 doc/quickstart.html (limited to 'doc/quickstart.html') diff --git a/doc/quickstart.html b/doc/quickstart.html new file mode 100644 index 000000000..44d73abc5 --- /dev/null +++ b/doc/quickstart.html @@ -0,0 +1,323 @@ + + + +Introduction to FreeS/WAN + + + + +Contents +Previous +Next +
+

Quickstart Guide to Opportunistic Encryption +

+ +

Purpose

+

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.

+

OE "flag day"

+

As of FreeS/WAN 2.01, 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 require additional resource records, as detailed in our + upgrading document. OE setup instructions here are for 2.02 or + later.

+

Requirements

+

To set up opportunistic encryption, you will need:

+ +

Note: Currently, only Linux FreeS/WAN supports opportunistic + encryption.

+

RPM install

+

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 + install document.

+

Download RPMs

+

If we have prebuilt RPMs for your Red Hat system, this command will + get them:

+
    ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/`uname -r | tr -d 'a-wy-z'`/\*
+

If that fails, you will need to try another + install method. Our kernel modules will only work on the Red Hat + kernel they were built for, since they are very sensitive to small + changes in the kernel.

+

If it succeeds, you will have userland tools, a kernel module, and an + RPM signing key:

+
    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
+

Check signatures

+

If you're running RedHat 8.x or later, import the RPM signing key + into the RPM database:

+
    rpm --import freeswan-rpmsign.asc
+

For RedHat 7.x systems, you'll need to add it to your + PGP keyring:

+
    pgp -ka freeswan-rpmsign.asc
+

Check the digital signatures on both RPMs using:

+
    rpm --checksig freeswan*.rpm
+

You should see that these signatures are good:

+
    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
+

Install the RPMs

+

Become root:

+
    su
+

Install your RPMs with:

+

+
    rpm -ivh freeswan*.rpm
+

If you're upgrading from FreeS/WAN 1.x RPMs, and have problems with + that command, see this note +.

+

Then, start FreeS/WAN:

+
    service ipsec start
+

Test

+

To check that you have a successful install, run:

+
    ipsec verify
+

You should see as part of the verify output:

+
+    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]
+    ...
+

If any of these first four checks fails, see our + troubleshooting guide.

+

Our Opportunistic Setups

+

Full or partial opportunism?

+

Determine the best form of opportunism your system can support.

+ +

Initiate-only setup

+

Restrictions

+

When you set up initiate-only Opportunistic Encryption (iOE):

+ +

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.

+

Create and publish a forward DNS record

+

Find a domain you can use

+

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 + this one, also provide this service.

+

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.

+

Choose your ID

+

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:

+
    [root@xy root]# hostname --fqdn
+    xy.example.com
+

This name in FQDN (fully-qualified domain name) format will be your + ID, for DNS key lookup and IPsec negotiation.

+

Create a forward TXT record

+

Generate a forward TXT record containing your system's public key + with a command like:

+
    ipsec showhostkey --txt @xy.example.com
+

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):

+
+    ; RSA 2192 bits   xy.example.com   Thu Jan  2 12:41:44 2003
+        IN      TXT     "X-IPsec-Server(10)=@xy.example.com" 
+    "AQOF8tZ2... ...+buFuFn/"
+
+

Publish the forward TXT record

+

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.

+

Test that your key has been published

+

Check your DNS work

+
    ipsec verify --host xy.example.com
+

As part of the verify output, you ought to see something + like:

+
    ...
+    Looking for TXT in forward map: xy.example.com          [OK]
+    ...
+

For this type of opportunism, only the forward test is relevant; you + can ignore the tests designed to find reverse records.

+

Configure, if necessary

+

If your ID is the same as your hostname, you're ready to go. + FreeS/WAN will use its built-in connections + to create your iOE functionality.

+

If you have chosen a different ID, you must tell FreeS/WAN about it + via ipsec.conf:

+
    config setup
+        myid=@myname.freedns.example.com
+

and restart FreeS/WAN:

+
    service ipsec restart
+

The new ID will be applied to the built-in connections.

+

Note: you can create more complex iOE configurations as explained in + our policy groups document +, or disable OE using + these instructions.

+

Test

+

That's it! Test your connections.

+ +

Full Opportunism

+

Full opportunism allows you to initiate and receive opportunistic + connections on your machine.

+ +

Put a TXT record in a Forward Domain

+

To set up full opportunism, first set up a + forward TXT record as for initiator-only OE +, using an ID (for example, your hostname) that resolves to your IP. Do + not configure /etc/ipsec.conf, but continue with the + instructions for full opportunism, below.

+

Note that this forward record is not currently necessary for full OE, + but will facilitate future features.

+ +

Put a TXT record in Reverse DNS

+

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.

+

Create a Reverse DNS TXT record

+

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.

+

Use the command:

+
    ipsec showhostkey --txt 192.0.2.11
+

where you replace 192.0.2.11 with your public IP.

+

The record (with key shortened) looks like:

+
    ; 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/"
+

Publish your TXT record

+

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.

+

Test your DNS record

+

Check your DNS work with

+
    ipsec verify --host xy.example.com
+

As part of the verify output, you ought to see something + like:

+
    ...
+    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK]
+    ...
+

which indicates that you've passed the reverse-map test.

+

No Configuration Needed

+

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 private-or-clear, 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 policy groups + document, or disable OE using + these instructions.

+

If you've previously configured for initiator-only opportunism, + remove myid= from config setup, so that peer + FreeS/WANs will look up your key by IP. Restart FreeS/WAN so that your + change will take effect, with

+
    service ipsec restart
+

Consider Firewalling

+

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 our + firewall document for sample iptables rules.

+

Test

+

That's it. Now, test your connection.

+

Test

+

Instructions are in the next section.

+

Testing opportunistic connections

+

Be sure IPsec is running. You can see whether it is with:

+
    ipsec setup status
+

If need be, you can restart it with:

+
    service ipsec restart
+

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:

+

+
   links oetest.freeswan.org
+
   links oetest.freeswan.nl
+ + +

A positive result looks like this:

+
+   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
+
+

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 testing document. If you have + difficulty, see our OE troubleshooting tips.

+

Now what?

+

Please see our policy groups document + for more ways to set up Opportunistic Encryption.

+

You may also wish to make some pre-configured + connections.

+

Notes

+ + +

Troubleshooting OE

+

See the OE troubleshooting hints in our + troubleshooting guide.

+ +

Known Issues

+

Please see this list of known + issues with Opportunistic Encryption.

+
+Contents +Previous +Next + + -- cgit v1.2.3