Quickstart Guide to Opportunistic Encryption

* NEW * FreeS/WAN version 2 or better comes with an Opportunistic connection for your machine. To enable it simply set up DNS entries as described below.

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.

Opportunistic encryption is new technology and we are still working out some fine points. Please see this list of known issues.

Requirements

To set up opportunistic encryption, you will need:

to be running Linux
to install Linux FreeS/WAN 2.00-pre3 or better
either control over your reverse DNS (for full opportunism) or the ability to write to some forward domain (for initiator-only)
(for full opportunism) a static IP

Note: Only Linux FreeS/WAN supports opportunistic encryption.

RPM installation

Our instructions are for a recent Red Hat with a stock Red Hat kernel. For other ways to install, see our install document.

Please note: We are not making a full set of RPMs for the 2.00-pre series. Sorry for the inconvenience.

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-module-2.00_2.4.18_3-0.i386.rpm
    rpm --checksig freeswan-userland-2.00_2.4.18_3-0.i386.rpm

You should see:

    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-module-2.00_2.4.18_3-0.i386.rpm

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

Then, start FreeS/WAN:

    service ipsec start

Test

To check that you have a successful install, run:

    ipsec verify

You should see at least:

    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 fullest 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 + KEY Records 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 yourself up as an opportunistic initiator:

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.
At one point, we thought that you could also have NATted nodes behind this machine, but this doesn't seem to work with iptables rules. Feel free to prove us wrong.

Put your public key in DNS

Find a domain you can use

Find a DNS forward domain where you can publish your key. You'll need access to the DNS zone files for that domain. For the following examples, we'll use "example.com".

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 KEY record

Generate a DNS KEY record containing your system's public key with the command:

    ipsec showhostkey

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 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
    xy.example.com.   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/

Change xy.example.com to your FQDN.

Publish the KEY

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

ipsec verify

Check your DNS work

    ipsec verify --host xy.example.com

You ought to see something like:

    Looking for forward key for xy.example.com      [OK]

For this type of opportunism, only the forward key test is relevant.

...or with a direct nameserver query

If your FreeS/WAN is older than 1.98b, query your nameserver (here, 1.2.3.254):

    dig @1.2.3.254 xy.example.com KEY

You should see (with the key again shortened):

    ;; ANSWER SECTION:
    xy.example.com.		6835	IN	KEY	16896 4 1 AQO6DJc6LIwGq82ehvIGLKn4S...

Configure

You must clone the default connection OEself inipsec.conf, changing leftid to point at the domain where you've published your DNS records.

Find conn OEself in /etc/ipsec.conf. Remove the comments preceding each line. Add a line such as

    leftid=@xy.example.com   # put your ID here

with your FQDN ID, preceded by an @sign, is in place of@xy.example.com.

Restart FreeS/WAN so that the new configuration takes effect:

    service ipsec restart

Test

That's it! Test your connection

Full Opportunism

This allows you to initiate and receive opportunistic connections from one machine.

Put KEY and TXT records in DNS

Your KEY record

Generate a KEY record:

    ipsec showhostkey

This command takes the contents of /etc/ipsec.secrets and reformats it into something usable by ISC's BIND. It will yield (with key data trimmed for clarity):

    ; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
  xy.example.com   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/

Edit it to insert the IP address in reverse map format. In our example, 1.2.3.4 becomes 4.3.2.1.in-addr.arpa. The result:

    ; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
  4.3.2.1.in-addr.arpa.   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/

Your TXT record

This lets others know that this machine can receive opportunistic connections. It also lets them know that the machine is authorized to encrypt on its own behalf.

Use the command:

    ipsec showhostkey --txt 1.2.3.4

where you replace 1.2.3.4 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)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

Publish both records

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 records

ipsec verify

Check your DNS work

    ipsec verify --host xy.example.com

You ought to see something like:

    Looking for TXT in reverse map: 4.3.2.1.in-addr.arpa [OK]
    Looking for KEY in reverse map: 4.3.2.1.in-addr.arpa [OK]

which indicates that you've passed both reverse-map tests.

or the long way...

Test that your KEY has been published by querying your nameserver (here, 1.2.3.254):

    dig @1.2.3.254 4.3.2.1.in-addr.arpa. KEY

You should see (with the key shortened for clarity):

    ;; ANSWER SECTION:
    4.3.2.1.in-addr.arpa.		6835	IN	KEY	16896 4 1 AQO6DJc6LIwGq82ehvIGLKn4S...

Next, test that your TXT record is visible:

    dig @1.2.3.254 4.3.2.1.in-addr.arpa. TXT

You should see (with the key shortened for clarity):

    ;; ANSWER SECTION:
    4.3.2.1.in-addr.arpa. 7200 IN	TXT	"X-IPsec-Server(10)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

Configuration is unneccessary

FreeS/WAN will use the hidden connection OEself.

If you've previously configured for initiator-only opportunism, remove your custom conn OEself, and restart FreeS/WAN

    service ipsec restart

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 rules you can add to /etc/sysconfig/iptables to permit this.

Test

That's it. Now, test your connection.

An Opportunistic Gateway

Start from full opportunism

Do as above, with one difference -- collect all the DNS records you'll need before contacting your ISP.

TXT records for each protected machine

You need these so that your Opportunistic peers can:

discover the gateway's address, knowing only the IP address that packets are bound for
verify that the gateway is authorised to encrypt for that endpoint

On the gateway, generate a TXT record with:

    ipsec showhostkey --txt 1.2.3.4

Use your gateway address in place of 1.2.3.4

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)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

This MUST BE the same key as in your gateway's KEY 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)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
    IN TXT  "X-IPsec-Server(10)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
    IN TXT  "X-IPsec-Server(10)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

Above each entry, insert a line like this:

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

It must include:

The subnet node's address in reverse map format. For example, 42.42.42.1 becomes 1.42.42.42.in-addr.arpa. Note the final period.
IN PTR
The node's name, ie. arthur.example.com

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

    1.42.42.42.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)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

    2.42.42.42.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)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

    3.42.42.42.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)=1.2.3.4" " AQOF8tZ2...+buFuFn/"

Publish your records

Ask your ISP to publish these records in your reverse map.

...and test them

ipsec verify

Check a couple of records with commands like this one:

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

You should see:

    ....
    Looking for TXT in reverse map: 2.42.42.42.in-addr.arpa [OK]
    ....
    Looking for TXT in reverse map: 3.42.42.42.in-addr.arpa [OK]

...or the long way

Test a couple of records with commands like this one:

    dig @1.2.3.254 1.42.42.42.in-addr.arpa. TXT

Replace 1.2.3.254 with your nameserver's IP, and 1.42.42.42.in-addr.arpa. with the reverse-format IP of one of your subnet nodes.

You should see:

ANSWER SECTION:
1.42.42.42.in-addr.arpa. 180	IN	TXT	"X-IPsec-Server(10)=1.2.3.4 " AQOF8tZ2...+buFuFn/"

ipsec.conf(5) for an opportunistic gateway

Cut-n-paste this connection to /etc/ipsec.conf:

conn OEsubnet
       also=OEself  # inherits other settings from built in connection
       leftsubnet=42.42.42.0/24

Set leftsubnet to the local IP range that your OE gateway will protect.

Restart FreeS/WAN:

    service ipsec restart

Test

Proceed to the next section and test away.

Testing opportunistic connections

The quick method is:

   links oetest.freeswan.org

A thought for the paranoid -- the feds are probably watching that site. You should see:

   You  seem  to  be  connecting  from:  1.2.3.4 which DNS says is:
   xy.example.com
     _________________________________________________________________

   Status E-route
   OE    enabled    16    192.139.46.73/32    ->    1.2.3.4/32   =>
   tun0x2097@1.2.3.5
   OE    enabled    176    192.139.46.77/32    ->   1.2.3.4/32   =>
   tun0x208a@1.2.3.5

If you do not see this, see our FAQ.

If you do, congratulations! Your machine will now encrypt whenever it can.

Now what?

If you haven't already, read up on our known issues. Or, proceed to make some vpn connections.

Appendix: the hidden OE connection

In 2.00, OE is enabled by default. This is accomplished by automatically defining a conn "OEself" UNLESS the sysadmin defines one with the same name:

    conn OEself
        left=%defaultroute
        leftrsasigkey=%dnsondemand
        right=%opportunistic
        rightrsasigkey=%dnsondemand
        keyingtries=3
        ikelifetime=1h
        keylife=1h
        rekey=no
        auto=route

This will only work if %defaultroute works. The leftid will be the resulting IP address, so the connection won't work if you haven't filled in the reverse DNS entry. Unlike other conns, nothing in this implicit conn is changed by conn %default.

Contents Previous Next