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:

- a Linux box. For OE to the public Internet, this box must NOT be behind Network Address Translation (NAT).
- to install Linux FreeS/WAN 2.02 or later
- either control over your reverse DNS (for full opportunism) or the ability to write to some forward domain (for initiator-only). This free DNS service explicitly supports forward TXT records for FreeS/WAN use.
- (for full opportunism) a static IP

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.03_2.4.20_20.9-0.i386.rpm
        freeswan-userland-2.03_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.03_2.4.20_20.9-0.i386.rpm: pgp md5 OK
        freeswan-userland-2.03_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.

- For full opportunism, 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.
- If you have a dynamic IP, and/or write access to forward DNS only, you can do initiate-only opportunism
- To protect traffic bound for real IPs behind your gateway, use this form of full opportunism.

## Initiate-only setup

### Restrictions

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

- there will be no incoming connection requests; you can initiate all the IPsec connections you need.
- only one machine is visible on your end of the connection.
- iOE also protects traffic on behalf of NATted hosts behind the iOE box.

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

- 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.
- You may change this, and other settings, by altering the config setup section in /etc/ipsec.conf.
- Note that the built-in connections used to build policy groups do not inherit from conn default.
- 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.

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