More complex requirements are covered elsewhere:
However, please read this quick start section first, before tackling the others.
There are two easy ways to install FreeS/WAN:
If you are using one of them, just include FreeS/WAN in the choices you make during installation, or add it to your configuration later using the distribution's tools.
Sources for RPM packages of FreeS/WAN are:
Note that:
You need to download at least two RPMs:
Once you have them, install the RPMs with rpm -i commands. You will need to be root to install the kernel.
If your distribution does not include FreeS/WAN and no RPMs are available, see our installation from source document.
That's it. FreeS/WAN is installed.
RSA is a public key cryptographic technique. Keys are created as matched pairs. Each pair includes:
For FreeS/WAN, both keys for your system are in the ipsec.secrets(5) file. Maintaining security of this file is essential since it holds your private key.
To generate your key pair, give these commands as root:
ipsec newhostkey > /etc/ipsec.secrets chmod 600 /etc/ipsec.secrets
Key generation may take some time, even on a fast system. Also, it needs a
lot of random numbers so you may need to
switch consoles and do something like typing a lot of text or running
The RSA keys we generate are suitable only for authentication, not for encryption. IPsec uses them only for authentication. See our IPsec section for details.
Opportunistic encryption makes some aspects of the setup and administration of IPsec easier.
For opportunistic encryption, you do not need to communicate with the administrator of a site before establishing secure communications to that site. In particular, you do not have to send them your keys or collect and authenticate theirs. All you have to do is set up your end correctly and from there on, everything is automatic.
One of the major goals of the FreeS/WAN project is to get opportunistic encryption widely enough deployed that a "FAX effect" comes into play. Neither a FAX machine nor opportunistic encryption is of much value if there are only a few installed, but both become much more useful as the installed base increases.
Widespread deployment of opportunistic encryption appears to be our best hope for making the Internet more secure. See discussion in our introduction.
In this section, we treat the simplest case of opportunistic encryption:
This would apply to a standalone machine, or to a home gateway with some invisible NAT clients.
Given the above conditions, you can set up opportunistic encryption without having access to the DNS reverse map for your machine. The following sections cover situations where one or more of the above restrictions do not apply.
There are two steps:
Once this is done, your system will automatically encrypt whenever it can.
# general IPsec setup config setup # Use the default interface interfaces=%defaultroute # Use auto= parameters in conn descriptions to control startup actions. plutoload=%search plutostart=%search # defaults for subsequent connection descriptions conn %default # How to authenticate gateways authby=rsasig # default is # load connection description into Pluto's database # so it can respond if another gatway initiates # individual connection descriptions may override this auto=add # description for opportunistic connections conn me-to-anyone also=our_stuff # our system details, stored below right=%opportunistic # anyone we can authenticate rightrsasigkey=%dns # look up their key in DNS auto=route # set up for opportunistic rekey=no # let unused connections die # description of our system # included in other connection descriptions via also= lines # must come after the lines that use it conn our_stuff # all connections should use our default route # also controls the source address on IPsec packets left=%defaultroute # our identity for IPsec negotiations # must match what is in DNS and ipsec.secrets(5) leftid=@xy.example.com
The last line above is the only one that you need to edit for your system. All the rest is identical for any standalone machine doing opportunistic encryption.
There is no need to provide any keys in this file. Your private key is in ipsec.secrets(5) and, for opportunistic encryption, the public keys for remote gateways are all looked up in DNS.
Also note that the left and right designations here are arbitrary. You could reverse them above with no problems.
For example, a reverse lookup on the IP address for a home gateway might give 123.adsl.kalamazoo.example.net, and a forward lookup for example.dyndns.org might point to that gateway. You could use either of these names as your ID for IPsec purposes, if the admins at either example.net or dyndns.org co-operate.
If not, you can use any domain whose DNS administrator is willing to help out. You do not need an A record (address record, associating your chosen name with an address) in that domain, only a KEY record.
You can generate a DNS KEY record containing your system's public key with the command:
ipsec showhostkeyThe 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/
The name here is taken from ipsec.secrets(5). If it is not what you want, edit that file to correct it, then run ipsec showhostkey again.
The name must also match what you used for rightid= in ipsec.conf(5).
Give this record to the DNS administrator, for insertion into the zone file of the domain.
The first step is to allow IPsec packets (IKE on UDP port 500 plus ESP, protocol 50) in and out of your gateway. A script to set up iptables(8) rules for this is:
# edit this line to match the interface you use as default route # ppp0 is correct for many modem, DSL or cable connections # but perhaps not for you world=ppp0 # # allow IPsec # # IKE negotiations iptables -A INPUT -p udp -i $world --sport 500 --dport 500 -j ACCEPT iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT # ESP encrypton and authentication iptables -A INPUT -p 50 -i $world -j ACCEPT iptables -A OUTPUT -p 50 -o $world -j ACCEPT
Optionally, you could restrict this, allowing these packets only to and from a list of known gateways.
A second firewalling step -- access controls built into the IPsec protocols -- is automatically applied:
Optionally, you can add a third step using whatever additional firewall rules are required for your situation. These rules can recognise packets emerging from IPsec. They are marked as arriving on an interface such as ipsec0, rather than eth0, ppp0 or whatever. For example, in an iptables(8) rule set, you would use:
If using a bowser is inconvenient, take these steps:
When FreeS/WAN cannot set up an opportunistic connection, and no explicit tunnel has been configured, its default is to allow the traffic through in the clear. For the non-opportunistic host, you should see a %pass eroute (IPsec route), the FreeS/WAN mechanism that implements that default.
There are two steps in the setup.
Both need to be a little different than in the initiate-only case.
For incoming connections, you are not the initiator so you cannot use the first message to tell the other end the identity you wish to use. You must be able to handle having the other end identify you by IP address. In many cases, that will be all the remote gateway knows.
# description of our system # included in other connection descriptions via also= lines # must come after the lines that use it conn our_stuff # all connections should use our default route # also controls the source address on IPsec packets left=%defaultroute # our identity for IPsec negotiations # must match what is in DNS and ipsec.secrets(5) leftid=1.2.3.4
You must make a matching change in ipsec.secrets(5), so that the identifier for your secret key is also "1.2.3.4".
The record you need looks like this:
; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000 4.3.2.1.in-addr.arpa. IN KEY 0x4200 4 1 AQOF8tZ2...+buFuFn/
Generate a record with
As always, IP addresses in the reverse map are written backwards. In the above example, the gateway IP address is 1.2.3.4.
However, there are additional security concerns when you allow incoming opportunistic connections. This creates an additional path to your machine, so you need to check your rules to see that this does not provide a means for EvilDoers to bypass protections you have set up on other paths.
In particular, look at any rules you have that depend on interfaces, rules using -i ppp+, -o eth1 or similar expressions. You may need analogous rules for your ipsec interfaces.
Next we expand from a standalone system (which protects only its own traffic) to a gateway (which protects traffic for other systems).
There is one special case in which gateway configuration is quite simple -- if all the machines behind the gateway are hidden from the Internet. We describe that first, then go on to describe gateways for visible clients.
If your gateway uses NAT to allow machines to access the Internet without having their own routable IP addresses, then from the point of view of anyone else on the Internet:
Many gateways will need to support client systems which have routable addresses and are visible to the Internet. This involves:
You need only make a few additions to in the ipsec.conf(5) file:
The additions to the ipsec.conf(5) file might be:
# opportunistic connections for client systems # our gateway will build opportunistic tunnels on behalf of any # machine in the specified subnet conn subnet-to-anyone also=gate_stuff # our system details, stored below also=public_subnet # subnet description, below auto=route # set up for opportunistic right=%opportunistic # anyone we can authenticate via DNS rekey=no # let unused connections die # description of the subnet this gateway encrypts for # numbers used here are arbitrary, just for example conn public_subnet leftsubnet=42.42.42.0/24
There is one small thing to be careful of here. An also= line must appear in the file before the conn it references, so the first section above must appear before conn gate_stuff.
# opportunistic connections for additional systems conn second-to-anyone also=gate_stuff # our system details, stored below also=second_subnet # subnet description, below right=%opportunistic # anyone we can authenticate via DNS rekey=no # let unused connections die # description of a second subnet this gateway encrypts for # numbers used here are arbitrary, just for example conn second_subnet leftsubnet=101.102.103.0/24
again, you need a little care so that also= lines always come before the sections they reference.
The subnets used in these descriptions need not correspond to physical subnets. This is discussed in more detail in our advanced configuration document.
We assume you already have a KEY record in the reverse map so your gateway can accept incoming connections as described above.
For the gateway to provide an opportunistic encryption service for other systems, it must be possible for the initiator of an IPsec connection to:
; 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 record must be generated on the gateway so it can get the key from ipsec.secrets(5). The command is:
ipsec showhostkey --txt 1.2.3.4You must supply the gateway IP address on the command line.
One of these records is required in the reverse map for each system using this gateway for opportunistic IPsec. You insert it in the reverse map part of the zone file right after the line for that system's IP address, so part of the file might look 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/"You need one TXT record per client, but the TXT records can all be identical.
However, on a gateway there are additional things to do:
You need additional rules to handle these things. For example, adding some rules to the set shown above we get:
# edit this line to match the interface you use as default route # ppp0 is correct for many modem, DSL or cable connections # but perhaps not for you world=ppp0 # # edit these lines to describe your internal subnet and interface localnet=42.42.42.0/24 internal=eth1 # # allow IPsec # # IKE negotiations iptables -A INPUT -p udp -i $world --sport 500 --dport 500 -j ACCEPT iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT # ESP encrypton and authentication iptables -A INPUT -p 50 -i $world -j ACCEPT iptables -A OUTPUT -p 50 -o $world -j ACCEPT # # packet forwarding for an IPsec gateway # simplest possible rules $ forward everything, with no attempt to filter # # handle packets emerging from IPsec # ipsec+ means any of ipsec0, ipsec1, ... iptables -A FORWARD -d $localnet -i ipsec+ -j ACCEPT # simple rule for outbound packets # let local net send anything # IPsec will encrypt some of it iptables -A FORWARD -s $localnet -i $internal -j ACCEPT
On a production gateway, you would no doubt need tighter rules than the above. For details, see:
A common requirement is for pre-configured connections between a specfic network and some set of remote machines. For example, an office network will often need to provide remote access services for:
We refer to the remote machines as "Road Warriors". For purposes of IPsec, anyone with a dynamic IP address is a road warrior.
Of course, if both the warrior and the gateway at the office are set up for opportunistic encryption, then you may not need the pre-configured connection. Here we assume that you do need it. For example:
This section has three sub-sections:
On either end, the opportunistic setup is unaffected by this. You leave it in place so both systems can continue to do opportunistic encryption with everyone but each other.
To set up an explicitly configured connection, you need some information about the system on the other end.
Connection descriptions use left and right to designate the two ends. We adopt the convention that, from the gateway's point of view left=local and right=remote.
The gateway administrator needs to know some things about each Road Warrior:
To get this information, in a format suitable for insertion directly into the gateway's ipsec.conf(5) file, issue this command on the Warrior machine:
ipsec showhostkey --rightThe output should look like this (with the key shortened for easy reading):
rightid=@xy.example.com rightrsasigkey=0s1LgR7/oUM...
The Road Warrior needs to know:
This information should be provided in a convenient format, ready for insertion in the Warrior's ipsec.conf(5) file. For example:
left=1.2.3.4 leftsubnet=42.42.42.0/24 leftid=@gateway.example.com leftrsasigkey=0s1LgR7/oUM...
The gateway administrator typically needs to generate this only once. The same file can be given to all Warriors.
Of course it is also possible to provide different versions (in particular, access to differnet subnets) to different groups of Warriors. See our advanced configuration document.
To set up a Road Warrior machine, we start from the opportunistic imitiator setup shown above.
We need to add a connection description for the pre-configured tunnel. Since we want to be right in that description, we reverse the opportunistic description so we are right there too.
# description for opportunistic connections # reversed from previous example conn me-to-anyone also=our_stuff # our system details, stored below left=%opportunistic # anyone we can authenticate leftrsasigkey=%dns # look up their key in DNS auto=route # set up for opportunistic rekey=no # let unused connections die # pre-configured link to office network # added for this example conn us-to-office also=our_stuff # our system details, stored below # # information obtained from office system admin # goes to the right of the = signs in these lines # values shown here are just for example # left=1.2.3.4 # gateway IP address lefttsubnet=42.42.42.0/24 # the office network leftid=@gateway.example.com # real keys are much longer than shown here leftrsasigkey=0s1LgR7/oUM... # description of our system # included in other connection descriptions via also= lines # must come after the lines that use it # reversed from previous example conn our_stuff # all connections should use our default route # also controls the source address on IPsec packets right=%defaultroute # our identity for IPsec negotiations # must match what is in DNS and ipsec.secrets(5) righttid=@xy.example.com
Everything else remains as it was when we had only opportunistic connections.
We could easily add more connections as required, perhaps one each for his office, her office, the kid's school, ... The file would grow longer, but nothing already in the file would need to change.
Adding road warrior support so people can connect remotely to your office network is straightforward.
We start from the opportunistic gateway setup shown above.
Instead, we suggest you give each warrior its own file, choosing some directory and naming convention that suits your system and style.
For this example, we use the directory /etc/ipsec.road and use filenames based on IPsec ID, so the Warrior using ID xy.example.com gets a file named xy.conf.
Using such files, you need add only one line to ipsec.conf(5). With our naming convention, the line is:
include /etc/ipsec.road/*.conf
FreeS/WAN will then read all those files and behave as if they were part of the ipsec.conf(5) file.
This needs to come before the conn gate_stuff section, so that the Warriors' connection descriptions can use also=gate_stuff. A convenient place for the line is right after the conn %default section.
Each of the Road Warrior files then contains a connection description for that Warrior. For example:
# connection description for Road Warrior "xy" conn gate-xy # use the gateway description in ipsec.conf(5) also=gate_stuff # allow connection attempt from any address # attempt fails if caller cannot authenticate right=%any # authentication information rightid=@xy.example.com rightrsasigkey=0s1LgR7/oUM...
With this technique, it becomes fairly simple to administer a gateway that supports many Road Warriors. For example:
To add a new user, simply add a suitable file.
To disable an account -- for example if a key is compromised -- first remove the file, then take any existing connection down with:
ipsec auto --down connectionand delete it from Pluto's internal database with:
ipsec auto --delete connection
If you have many users, it would be worthwhile to write scripts to automate such tasks.
Of course, if both offices are set up for opportunistic encryption and the security policies in place allow you to use that, explicitly configured tunnels become unnecessary. However, this will not always be the case.
Of course, a network-to-network tunnel requires its own connection description, so you have to add that. There are two ways to do this.
# sample tunnel # The network here looks like: # leftsubnet====left----leftnexthop......rightnexthop----right====rightsubnet # If left and right are on the same Ethernet, omit leftnexthop and rightnexthop. conn sample # left security gateway (public-network address) left=10.0.0.1 # next hop to reach right leftnexthop=10.44.55.66 # subnet behind left (omit if there is no subnet) leftsubnet=172.16.0.0/24 # right s.g., subnet behind it, and next hop to reach left right=10.12.12.1 rightnexthop=10.88.77.66 rightsubnet=192.168.0.0/24 auto=startIf you give an explicit IP address for left (and left and right are not directly connected), then you must specify leftnexthop (the router which left sends packets to in order to get them delivered to right). Similarly, you may need to specify rightnexthop (vice versa).
The *nexthop parameters are needed because of an unfortunate interaction between FreeS/WAN and the kernel routing code. They will be eliminated in a future release, but perhaps not soon. We know they should go, but getting them out is not a simple problem.
This description can be generated on either machine and simply inserted in the ipsec.conf(5) file on the other. No change is required or desired.
When using left=%defaultroute, you do not need to specify leftnexthop. left does not need to know rightnexthop either, so on left the connection description can be:
conn sample # left security gateway (public-network address) left=%defaultroute # subnet behind left (omit if there is no subnet) leftsubnet=172.16.0.0/24 # right s.g., subnet behind it right=10.12.12.1 rightsubnet=192.168.0.0/24 auto=startOn right it is:
conn sample # left security gateway (public-network address) left=10.0.0.1 # subnet behind left (omit if there is no subnet) leftsubnet=172.16.0.0/24 # right s.g., subnet behind it right=%defaultroute rightsubnet=192.168.0.0/24 auto=start
At this point, we have covered setup for opportunistic encryption and for simple cases of Road warrior and VPN connections. You have several choices for what to look at next: