Introduction to strongSwan

It is assumed that the reader of this document…​

If you don’t have such knowledge, there exist many ready-to-use appliances that provide remote IPsec access.

strongSwan is a complete IPsec solution providing encryption and authentication to servers and clients. strongSwan can be used to secure communications with remote networks, so that connecting remotely is the same as connecting locally.

On our website you’ll find dozens of complete configuration examples covering these and similar situations.

strongSwan is basically a keying daemon that uses the Internet Key Exchange Version 2 (IKEv2) protocol to establish Security Associations (SAs) and negotiate Security Policies (SPs) between two peers. For legacy applications IKEv1 is still supported, although we strongly discourage from using IKEv1 due to stability and some security reasons (it is now officially deprecated).

IKE provides strong authentication of both peers and derives unique cryptographically-strong session keys. Such an IKE session is often denoted IKE_SA in our documentation. Besides authentication and key material IKE also provides the means to exchange configuration information (e.g. virtual IP addresses) and to negotiate IPsec SAs, which are often called CHILD_SAs. IPsec SAs define which network traffic is to be secured and how it has to be encrypted and authenticated.

A CHILD_SA consists of two components:

The policies work both ways, i.e. only traffic matching an inbound policy will be allowed after decryption. Policies are derived from the traffic selectors (TS) negotiated via IKE when establishing a CHILD_SA. Unprotected traffic that the kernel receives and for which there is no matching inbound IPsec policy will be dropped. This is a security feature.

The actual IPsec traffic is not handled by strongSwan but will be relegated to the network and IPsec stack of the operating system kernel. strongSwan installs the negotiated IPsec SAs and SPs into the kernel by using a platform-dependent kernel interface.

The mentioned distinction between policies and SAs often leads to misconceptions. For instance, referring to the image above, if host moon has a site-to-site tunnel to host sun (connecting the two networks 10.1.0.0/16 and 10.2.0.0/24) and host carol has a roadwarrior connection to host sun (from which carol received a virtual IP address of 10.3.0.10). Then carol won’t be able to automatically communicate with alice, even if forwarding is enabled on sun. This is because there is no IPsec policy allowing traffic between carol (10.3.0.10) and alice (10.1.0.10). An additional SA between moon and sun connecting the virtual subnet 10.3.0.0/24 with 10.1.0.0/16 would be a possible solution to this issue.

Generally, IPsec processing and routing are not directly related. IPsec is often just bumped into the network stack and matching traffic is processed transparently (policy-based). So any routes to the remote TS will technically work for packets to get forwarded and processed by IPsec. However, source address selection can be a problem when traffic is sent from the VPN host itself. If the local TS don’t include its "public" address, traffic would not get processed if the source address is e.g. selected based on the default route. This is particularly true if virtual IP addresses are used. So to ensure that an address from a local TS is selected as source, the strongSwan charon IKE daemon, by default, installs specific routes to the remote TS for most CHILD_SAs (excluded are e.g. those that use transport mode or TS with specific ports/protocol).

An alternative approach is route-based IPsec that uses interfaces and explicit routes to control what packets are going to be processed by IPsec tunnels (traffic routed that way still has to match the negotiated policies).

To ensure that the peer with which an IKE_SA is established is really who it claims to be, it has to be authenticated.

strongSwan provides several methods to do this:

With IKEv2 it is possible to use multiple authentication rounds (RFC 4739), for instance to first authenticate the machine with an X.509 certificate and then the user with a username/password-based authentication scheme (e.g EAP-MSCHAPv2). It is also possible to use asymmetric authentication, e.g. by authenticating the gateway with a certificate and the client with a username/password-based EAP method in the first authentication round. Please be aware that not all IKEv2 implementations support the RFC 4739 extension.

Again, our website provides dozens of configuration examples covering these and other authentication options.

The recommended way of configuring strongSwan is via the powerful vici control interface and the swanctl command line tool. The swanctl.conf configuration file used by swanctl is stored together with certificates and corresponding private keys in the swanctl directory.

Global strongSwan settings as well as plugin-specific configurations are defined in strongswan.conf.

Alternatively, the legacy stroke control interface and the ipsec command line tool can be used with the deprecated ipsec.conf and ipsec.secrets configuration files.

The strongSwan installation is covered in a separate document.

Using binary packages provided by your distribution is generally recommended, as it makes maintenance easier. Unfortunately, this means that you are often not able to use the most recent version.

strongSwan is usually managed with the swanctl command while the IKE charon is controlled by systemd on modern distros. With legacy installations, strongSwan is controlled by the ipsec command where ipsec start will start the starter daemon which in turn starts and configures the keying charon daemon.

IKE Connections and CHILD SAs defined in swanctl.conf can be started through three different ways:

After an SA has been established, swanctl --terminate may be used to tear down the IKE_SA or individual CHILD_SAs.

Whenever the swanctl.conf file or credentials in the swanctl directory are changed they may be reloaded with the different swanctl --load-.. commands. Already established connections are not affected by these commands (unless start_action = start is used). If a configuration update is required, the SAs or even the daemon must be restarted.

Using the different swanctl --list-.. commands will provide information about loaded or cached certificates, supported algorithms and loaded plugins.

If you run into problems, increasing the log level might help you understand what exactly went wrong. The different logging options are described in a separate document or the strongswan.conf man page. Recommended log settings for debugging problems may be found here.

Whenever you encounter a log message similar to received …​ error notify where the placeholder …​ is e.g. NO_PROPOSAL_CHOSEN or TS_UNACCEPTABLE, you should consult the logs of the remote peer in order to find out why that error notify was generated in the first place.

The swanctl --list-.. commands will provide information about the established and configured connections.

On Linux, the iproute2 package provides the ip xfrm state and ip xfrm policy commands to request detailed information about the IPsec SAs and policies installed in the kernel. Adding the -s option will display extensive statistical information like the number of transmitted or invalid packages. On other platforms the setkey command from the ipsec-tools package provides similar information.

tcpdump and wireshark are also often useful to debug problems.

When testing a connection with ping, make sure to select a source IP address (with the -I option) that is included in the local traffic selector (also see Site-to-Site Configurations below).

To use certificate-based authentication you’ll need to create either self-signed certificates or set up a complete public-key infrastructure (PKI), consisting of a Certificate Authority (CA), optional intermediate CAs and end-entity certificates plus Certificate Revocation Lists (CRLs) or alternative methods like OCSP to verify the validity of certificates.

One of the easiest ways to generate certificates is to use the pki tool. Since setting up a whole PKI can be quite complex we provide some simple instructions to get you started.

OpenSSL is also a widespread alternative to generate certificates, as are several GUI based CA management utilities. Microsoft’s Active Directory Certificate Services (AD CS) could also be used for large scale PKIs.

On Linux, strongSwan installs routes into routing table 220 by default and hence requires the kernel to support policy based routing.

You can make the charon daemon install the routes into any table you like or you can disable them completely. For that purpose the charon.install_routes, charon.routing_table and charon.routing_table_prio settings in strongswan.conf may be used. When a tunnel is established between two subnets, charon tries to find local IPs in the tunneled local subnets. Such an IP must be configurd with scope global to be viable for the lookup. If a valid IP is found, charon will install a route pointing to the remote subnet where the source IP is set to the found IP. This results in routes like the following:

In that example, the local IP would be 10.2.0.2. The remote subnet would be 10.1.0.0/24. This is done, so packets to the remote subnet are sent with the correct source IP. Thus the IPsec policies will match and traffic from the local machine to the remote subnet will be secured by IPsec.

To avoid conflicts with these routes (especially if virtual IP addresses are used), the kernel-netlink plugin manually parses the host’s routing tables to determine a suitable source address when sending IKE packets. On hosts with a (very) high number of routes this is quite inefficient. In that case, setting charon.plugins.kernel-netlink.fwmark in strongswan.conf is recommended, as it will allow using a more efficient source address lookup.

In order to detect connectivity changes, strongSwan parses the events that the kernel sends when a route is installed or deleted and hence could cause high CPU load when e.g. running on a system that receives a lot of routes via dynamic routing. Connectivity change detection can be disabled by setting charon.process_route = no in strongswan.conf.

If IPv6 is used, then make sure to bypass Neighbor Discovery Protocol (NDP) traffic if necessary. It is possible that you encounter MSS/MTU problems when tunneling traffic. Please refer to Forwarding and Split-Tunneling for details.

In this section we present example configurations for common remote access use cases. In these so called roadwarrior scenarios mobile clients will be able to connect to a remote network.

Because these clients most likely connect from unknown IP addresses, the gateway will use remote_addrs = %any to literally accept connections from anywhere. To simplify routing traffic back to the clients and because roadwarriors are often located behind one or more NAT devices, the use of virtual IP addresses is necessary.

The virtual IPs can either be from a distinct subnet or actually from the subnet behind the gateway by use of the farp plugin and optionally the dhcp plugin.

Whether roadwarriors will send all traffic to the gateway or use split-tunneling, i.e. only send traffic for specific destinations through the tunnel, is also something to consider. This is explained in more details in Forwarding and Split-Tunneling. That document also explains how traffic is forwarded to hosts behind the gateway.

We provide the following site-to-site configuration examples

The most important difference compared to the remote access case is that the initiator will not request a virtual IP address but instead use local_ts to tunnel traffic from one or more local subnets. With IKEv2 multiple subnets (in CIDR notation) can be added to local_ts/remote_ts separated by commas. If IKEv1 is used, a separate children.<child> subsection has to be added for each combination of local and remote subnet, as only the first subnet in local_ts/remote_ts will be used.

One thing that often confuses users new to IPsec is that testing a net-to-net scenario from either of the gateways often requires one to select the source address used specifically (e.g. with ping -I) because the external IP of either gateway might not be included in the tunneled subnets. If that is something you require, either add the external IPs to the list of subnets in local_ts/remote_ts or add a specific host-to-host config.

Host-to-host connections are very easy to setup. You basically have to set remote_addrs to the hostname or IP address of the peer and configure the desired authentication. Neither the local_ts nor remote_ts traffic selectors have to be set explicitly.

Again, our web site provides some practical host-to-host configuration examples.