Introduction to strongSwan
This document gives an introduction to strongSwan for new users (or for existing users wanting to catch-up).
It is assumed that the reader of this document…
understands the principles of networking, from setting IP addresses and DNS servers to basic firewalling
grasps the basic authentication concepts based on public-key cryptography and a public-key infrastructure (PKI)
knows how to install binary software packages or how to compile source code following instructions
is adept on the console
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.
The gateway is usually your firewall but this can be any host within your network. Often the gateway is also able to serve a small network with DHCP and DNS. In the image above the hosts
sunserve as gateways for the internal hosts
- Remote Access / Roadwarrior Clients
Usually, roadwarriors are laptops and other mobile devices connecting remotely to your home network via the gateway. In the image above
daverepresent roadwarriors who want to access either of the two networks behind the two gateways.
- Remote Hosts / Host-to-Host
This can be a remote web server or a backup system. This is illustrated in the image by host
winnetouand either of the gateways
sun. The connection between the two hosts can usually be initiated by either one of them.
- Remote Sites / Site-to-Site
Hosts in two or more subnets at different locations should be able to access each other. Again referring to the image above, the two subnets
sun, respectively, might be connected, so that e.g. the hosts
bobmay securely communicate with one another.
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) between two peers. For legacy applications IKEv1 is still supported, although we strongly discourage from using IKEv1 due to stability and some security reasons. 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 actual IPsec SAs (two of them are established, one in each direction) describing the algorithms and keys used to encrypt and authenticate the traffic.
The policies (there are at least two) that define which network traffic shall use that SA.
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.2.0.0/24) and host
carol has a roadwarrior connection to host
carol received a virtual IP address of
wont be able to automatically communicate with
alice, even if forwarding is
sun. This is because there is no IPsec policy allowing traffic
10.1.0.10). An additional SA
sun connecting the virtual subnet
10.1.0.0/16 would be a possible solution to this issue.
Generally IPsec processing and routing are two different topics. IPsec is often
just bumped into the stack (policy based) and the original routing decision for
the unprotected packet also applies to the protected packet. This is the reason
charon IKE daemon by default installs
specific routes to the remote part of the TS (in newer
charon versions (>5.5.0), routes aren’t installed
for transport mode CHILD_SAs). An exception to this is
route-based IPsec that uses interfaces to control
what packets are going to be processed by each tunnel to a unique participant.
Route-based IPsec is less flexible than
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:
- Public Key Authentication
RSA, ECDSA or EdDSA X.509 certificates are used to verify the authenticity of the peer.
Certificates can be self-signed (in which case they have to be installed on all peers) or signed by a common Certificate Authority (CA). The latter simplifies deployment and configuration a lot as the gateway only needs the CA certificate to authenticate all peers that provide a valid certificate signed by that CA.
In order to prevent man-in-the-middle attacks, the identity claimed by the peer has to be confirmed by the certificate, either by the
- Pre-Shared-Key Authenticiation (PSK)
A pre-shared-key is an easy-to-deploy option but it requires strong secrets to be secure.
If the PSK is known to many users (which is often the case with IKEv1 XAuth with PSK) any user who knows the secret could impersonate the gateway. Therefore this method is not recommended for large scale deployments.
- Extensible Authentication Protocol (EAP)
This covers several possible authentication methods, some are based on username/password-based authentication (EAP-MD5, EAP-MSCHAPv2, EAP-GTC) or on X.509 certificates (EAP-TLS). Some can even tunnel other EAP methods (EAP-TTLS, EAP-PEAP).
- eXtended Authentication (XAuth)
XAuth provides a flexible authentication framework within IKEv1. It is mainly used for username/password-based authentication. Also it is generally used as a second authentication method after a mutual authentication based on either X.509 certificates or PSK. With IKEv1 hybrid authentication it is however possible to authenticate the gateway with a certificate and use XAuth to authenticate the client, only.
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
Global strongSwan settings as well as plugin-specific configurations are defined
Alternatively, the legacy
stroke control interface and the
line tool can be used with the deprecated
strongSwan is usually managed with the
while the IKE
charon is controlled by
systemd on modern distros. With legacy installations, strongSwan is controlled
ipsec command where
ipsec start will start the
which in turn starts and configures the keying
IKE Connections and CHILD SAs defined in
can be started through three different ways:
- On traffic
start_action = trapis used, IPsec trap policies for the configured traffic (defined via
remote_ts) will be installed and traffic matching these policies will trigger acquire events that cause the daemon to establish the required IKE/IPsec SAs. This is also used for passthrough/drop IPsec policies, to let specific traffic bypass other policies/SAs or drop it completely.
- On startup
CHILD_SAs configured with
start_action = startwill automatically be established when the daemon is started. They are not automatically restarted when they go down for some reason. You need to specify other configuration settings (
close_actionto restart them automatically but even then, the setup is not bullet-proof and will potentially leak packets. You are encouraged to use trap policies and read the SecurityRecommendations to take care of any problems.
A connection that uses no
start_actionhas to be established manually with
swanctl --initiateor acts passively as a responder waiting for a peer/roadwarrior to connect. Depending on the configuration, it is also possible to use
swanctl --installto install policies manually for such connections as
start_action = trapwould do it on startup.
After an SA has been established,
swanctl --terminate may be used to tear
down the IKE_SA or individual CHILD_SAs.
swanctl.conf file or credentials
swanctl directory are changed they may be
reloaded with the different
swanct --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
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
… is e.g.
should consult the logs of the remote peer in order to find out why that
error notify was generated in the first place.
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
setkey command from the
ipsec-tools package provides similar
wireshark are also often useful to debug problems.
When testing a connection with
ping, make sure to select a source IP address
-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.
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.
The generated end entity certificates need to authenticate the corresponding remote IKE ID for peer authentication to succeed.
To authenticate against another strongSwan instance using one or several certificates (also attribute certificates might be used), the certificate must authenticate the IKE ID the host is sending.
If Alice tries to authenticate against Bob as Alice (herself) then Alice’s certificate must contain at least one
subjectAltName(SAN) field with the correct type (FQDN) and the value Alice or the
subjectDistinguishedName(DN), not the
commonName(CN) has to be Alice!
In other words you can use the complete
DNor any of the
SANfields (assuming the type is correct) as an IKE ID. See Notes regarding certificates for details.
Additionally, the certificate has to be trusted by Bob, either by being known beforehand by Bob to being valid, or the certificate being issued by a certificate authority (CA) Bob is trusting.
For authentication to succeed, the other peer has to possess the complete X.509 certificate trust chain from root certificate (the root CA) down to the end entity certificate (the host or user certificate) including all intermediate certificates (intermediate CAs). This is done either by sending any intermediate certificates to the remote host or the remote host already having them installed locally.
A root CA certificate which being at the top of the X.509 trust chain, is always
self-signed and can therefore be faked by anyone, is
never sent to another host.
Any peer must install the root CA certificate locally in a trustful way and never
accept any root CA certificates received over the network.
A local certificate is only sent to another host if at least one of the following settings are true:
The local host has set
connections.<conn>.send_cert = alwaysin the connection definition it is using.
The remote peer requests a certificate issued by a trusted CA by sending a CERTREQ payload to the local peer that indicates one of the CAs in the path from the local host’s certificate up to its root CA certificate.
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
strongswan.conf may be used. When
a tunnel is established between two subnets,
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
10.1.0.0/24 via 10.2.0.1 src 10.2.0.2
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 IPs addresses are used), the
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
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 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
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.
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.
The three strongSwan gateway configurations shown for the Windows clients may be used for all IKEv2 clients:
In all three use cases the gateway is authenticated by a certificate while the clients either authenticate themselves based on certificates (1, 2) or on username/password schemes (3). The generic EAP use case (3) incorporates the EAP-TLS use case (2), so that only two configurations (1, 3) must be implemented in parallel on a strongSwan VPN gateway to leave it up to the VPN clients to select any of the three authentication methods above.
eap-radius plugin, user authentication
may be delegated to a RADIUS server (e.g. an existing Active Directory DC).
Both the strongSwan VPN Client for Android and
NetworkManager may be used with any of the
strongSwan VPN gateway configurations. Alternatively the
charon-cmd command line IKEv2 client provides a
simple means to establish roadwarrior connections.
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
local_ts to tunnel traffic from one or more local subnets. With IKEv2
multiple subnets (in CIDR notation) can be added to
separated by commas. If IKEv1 is used, a separate
subsection has to be added for each combination of local and remote subnet, as only
the first subnet in
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
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
remote_ts traffic selectors
have to be set explicitly.
Again, our web site provides some practical host-to-host configuration examples.