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/src/quickstart.html | 458 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 458 insertions(+) create mode 100644 doc/src/quickstart.html (limited to 'doc/src/quickstart.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 @@ + + + + Quick FreeS/WAN installation and configuration + + + + +

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.

+ + + + -- cgit v1.2.3