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.
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.
To set up opportunistic encryption, you will need:
Note: Currently, only Linux FreeS/WAN supports opportunistic encryption.
Our instructions are for a recent Red Hat or Fedora Core with a 2.4-series stock or Red Hat/Fedora Core updated kernel. For other ways to install, see our install document.
If we have prebuilt RPMs for your Red Hat or Fedora Core 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 or Fedora Core 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.06_2.4.20_20.9-0.i386.rpm
freeswan-userland-2.06_2.4.20_20.9-0.i386.rpm
freeswan-rpmsign.asc
If you're running RedHat 8.x or later, or Fedora Core, 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.06_2.4.20_20.9-0.i386.rpm: pgp md5 OK
freeswan-userland-2.06_2.4.20_20.9-0.i386.rpm: pgp md5 OK
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
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.
Determine the best form of opportunism your system can support.
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.
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 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.
ipsec mailkey is a script which crafts an email to the DNS administrator for your chosen forward domain, asking them to publish the TXT record you will need for iOE. Invoke it with a command like:
ipsec mailkey --me me@example.com --forward xy.example.com
For me@example.com use your email address, and for xy.example.com use your chosen forward domain. You should see:
Executable mail file saved to: /root/OE_mail_xy.example.com
In the executable file, check that contact_mail is the correct address for your domain's administrator:
contact_mail=dnsadmin.example.com
To send the mail, execute the file:
/root/OE_mail_xy.example.com
It may take a day or so for the DNS administrator to publish the record, and that long again for the record to propagate. Periodically, check the DNS work with:
ipsec verify --host xy.example.com
If the record has been published correctly, you should see a line like:
...
Looking for TXT in forward map: xy.example.com [OK]
...
You can ignore the tests designed to find reverse records. If you don't see this result within 48 hours, speak to the DNS administrator.
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.
That's it! Test your connections.
Full opportunism allows you to initiate and receive opportunistic connections on your machine.
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.
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.
ipsec mailkey is a script which crafts an email to the DNS administrator for your reverse DNS, asking them to publish the TXT record you will need for full OE. Invoke it with a command like:
ipsec mailkey --me me@example.com --reverse 192.0.2.11
For me@example.com use your email address, and for xy.example.com use your public IP. You should see:
Executable mail file saved to: /root/OE_mail_192.0.2.11
In the executable file, check that contact_mail is the correct address for your reverse domain's administrator. Often this is your ISP's sysadmin:
contact_mail=dnsadmin.isp.example.com
To send the mail, execute the file:
/root/OE_mail_192.0.2.11
It may take a day or so for the DNS administrator to publish the record, and that long again for the record to propagate. Periodically, check the DNS work with:
ipsec verify --host xy.example.com
If the record has been published correctly, you should see a line like:
...
Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK]
...
which indicates that the TXT record has been successfully published in your reverse map. If you don't see this result within 48 hours, speak to the DNS administrator.
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
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.
That's it. Now, test your connection.
Instructions are in the next section.
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.
At first, FreeS/WAN may establish connections slowly. Often this occurs because it waits for DNS TXT record requests to time out. To speed the process, you may install a caching DNS locally and/or place your upstream DNS provider in the clear group.
For more detail on this or other difficulties, see our OE troubleshooting tips.
Please see our policy groups document for more ways to set up Opportunistic Encryption.
You may also wish to make some pre-configured connections.
See the OE troubleshooting hints in our troubleshooting guide.
Please see this list of known issues with Opportunistic Encryption.