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.

Please see this list of known issues with Opportunistic Encryption.

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 should post additional resource records, as detailed in our upgrading document. OE setup instructions here are for 2.01 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 stock Red Hat kernel. For other ways to install, see our install document.

Download RPMs

Check your kernel version with

   uname -a

From our FTP site, get the kernel module which matches your kernel. For example:

    freeswan-module-2.00_2.4.18_3-0.i386.rpm

Note: 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.

Get FreeS/WAN utilities to match. For example:

    freeswan-userland-2.00_2.4.18_3-0.i386.rpm

Check signatures

While you are there, grab the RPM signing key

    freeswan-rpmsign.asc

If you're running RedHat 8.x, import this 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 signatures on both RPMs using:

    rpm --checksig freeswan*.rpm 

You should see output like:

    freeswan-module-2.00_2.4.18_3-0.i386.rpm: pgp md5 OK
    freeswan-userland-2.00_2.4.18_3-0.i386.rpm: pgp md5 OK

Install the RPMs

Become root:

    su

Install your RPMs with:

    rpm -ivh freeswan*.rpm

If you've installed FreeS/WAN RPMS before, see our note on upgrading from 1.x to 2.x RPMs.

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. Normally, but not always, your ID is the same as your machine name. Our machine is called xy, and we'll choose the corresponding FQDN xy.example.com.

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 FQDN 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/"

Change the name which appears in the first line to your FQDN, if these differ.

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

Place this iOE connection in /etc/ipsec.conf. It's a copy of a built in OE connection, modified to use a custom ID:

conn iprivate-or-clear    
    leftid=@xy.example.com   # put your ID here
    also=private-or-clear

Use your own FQDN ID, preceded by an @sign, instead of @xy.example.com.

Create a group file for this connection in /etc/ipsec.d/policies . An OE connection will be instantiated for hosts within the CIDR blocks listed in its group file.

    cp -p /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/iprivate-or-clear

Make iprivate-or-clear your default policy by ensuring fullnet is in its group file:

    [root@xy root]# cat /etc/ipsec.d/policies/iprivate-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

Remove fullnet from /etc/ipsec.d/policies/private-or-clear , if it also appears there:

    [root@xy root]# cat /etc/ipsec.d/policies/private-or-clear
    ....
    # 0.0.0.0/0

Restart FreeS/WAN so the changes take effect:

    service ipsec restart

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 connection.

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 leftid= 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.

An Opportunistic Gateway

Start from full opportunism

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 these instructions. 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.

Reverse DNS TXT records for each protected machine

You need these so that your Opportunistic peers can:

On the gateway, generate a TXT record with:

    ipsec showhostkey --txt 192.0.2.11

Use your gateway address in place of 192.0.2.11.

You should see (keys are trimmed for clarity throughout our example):

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

This MUST BE the same key as in your gateway's TXT record, or nothing will work.

In a text file, make one copy of this TXT record for each subnet node:

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

Above each entry, insert a line like this:

    98.2.0.192.in-addr.arpa. IN PTR arthur.example.com.

It must include:

The result will be a file of TXT records, like this:

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

Publish your records

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.

...and test them

Check a couple of records with commands like this one:

    ipsec verify --host ford.example.com
    ipsec verify --host trillian.example.com

The verify command checks for TXT records for both the subnet host and its gateway. You should see output like:

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

No Configuration Needed

FreeS/WAN 2.x ships with a built-in, automatically enabled OE connection conn packetdefault which applies OE, if possible, to all outbound traffic routed through the FreeS/WAN box. The ipsec.conf(5) manual describes this connection in detail. While the effect is much the same as private-or-clear, the implementation is different: notably, it does not use policy groups.

You can create more complex OE configurations for traffic forwarded through a FreeS/WAN box, as explained in our policy groups document, or disable OE using these instructions.

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

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 each protected subnet node , load the FreeS/WAN website with:

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

A positive result looks like this:

   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

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 OE troubleshooting tips.

Additional OE tests

When testing OE, you will often find it useful to execute this command on the FreeS/WAN host:

   ipsec eroute

If you have established a connection (either for or for a subnet node) you will see a result like:

    192.0.2.11/32   -> 192.139.46.73/32  => tun0x149f@192.139.46.38

Key:

1.192.0.2.11/32Local start point of the protected traffic.
2.192.0.2.194/32Remote end point of the protected traffic.
3.192.0.48.38Remote FreeS/WAN node (gateway or host). May be the same as (2).
4.[not shown]Local FreeS/WAN node (gateway or host), where you've produced the output. May be the same as (1).

For extra assurance, you may wish to use a packet sniffer such as tcpdump to verify that packets are being encrypted. You should see output that indicates ESP encrypted data, for example:

    02:17:47.353750 PPPoE  [ses 0x1e12] IP 154: xy.example.com > oetest.freeswan.org: ESP(spi=0x87150d16,seq=0x55)

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

This table is a work in progress. We welcome contributions via the users' mailing list.

SymptomProblem Action
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:
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.)
The older FreeS/WAN logs no error.
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. 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.
OE host is very slow to contact other hosts.Slow DNS service while running OE.It's a good idea to run a caching DNS server on your OE host, as outlined in this mailing list message. If your DNS servers are elsewhere, put their IPs in the clear policy group, and re-read groups with
ipsec auto --rereadgroups
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.
Peer is not set up for OE.

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.

ipsec verify does not find DNS records:
...
Looking for TXT in forward map: 
                xy.example.com...[FAILED]
Looking for TXT in reverse map...[FAILED]
...
You also experience authentication failure:
Possible authentication failure:
no acceptable response to our 
first encrypted message
DNS records are not posted or have not propagated.Did you post the DNS records necessary for OE? If not, do so using the instructions in our quickstart guide. If so, wait up to 48 hours for the DNS records to propagate.
ipsec verify does not find DNS records, and you experience authentication failure.For iOE, leftid does not match location of forward DNS record.In your iOE connections, change leftid= to match the forward DNS where you posted the record. For reference, see our iOE instructions.
ipsec verify finds DNS records, yet there is still authentication failure. ( ? )DNS records are malformed. Re-create the records and send new copies to your DNS administrator.
ipsec verify finds DNS records, yet there is still authentication failure. ( ? )DNS records show different keys for a gateway vs. its subnet hosts.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 these instructions.
OE gateway loses connectivity to its subnet. The gateway's routing table shows routes to the subnet through IPsec interfaces. The subnet is part of the private or block policy group on the gateway.Remove the subnet from the group, and reread groups with
ipsec auto --rereadgroups
OE does not work to hosts on the local LAN.This is a known issue.See this list of known issues with OE.
FreeS/WAN does not seem to be executing your default policy. In your logs, you see a message like:
/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"
Fullnet 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). Find all policies which contain fullnet with:
grep -F 0.0.0.0/0 /etc/ipsec.d/policies/*
then remove the unwanted occurrence(s).

Contents Previous Next