Introduction to strongSwan¶

• Table of contents
• Introduction to strongSwan
  • Prerequisites
  • Securing a Network
  • IKE and IPsec Basics
  • Authentication Basics
  • Configuration Files
    • Terminology
    • Other Configuration Sources
  • Installation
  • Invocation and Maintenance
  • Logging and Monitoring
  • PKI
  • Remote Access Configurations
    • IKEv2 (Windows 7/8, Linux, Android 4+, Mac OS X, iOS 8+)
    • IKEv1 (iOS, Mac OS X, Android, Windows)
  • Site-to-Site Configurations
  • Host-to-Host Configurations

This document is intended to give an introduction to strongSwan for new users (or existing users with catching-up to do).

Prerequisites¶

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 concepts of authentication 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.
One such device is the revobox by revosec that is based on strongSwan.

Securing a Network¶

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

• Gateway: 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 moon and sun serve as gateways for the internal hosts alice and bob,
  respectively.
• Remote access / Roadwarrior clients: Usually, roadwarriors are laptops and other mobile devices
  connecting from remote to your network using the gateway. In the image above carol represents a
  roadwarrior who wants 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 winnetou and either of the gateways. 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 10.1.0.0/24 and 10.2.0.0/24 behind
  gateways moon and sun, respectively, might be connected, so that the hosts alice and bob may securely
  communicate with one another.

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

IKE and IPsec Basics¶

strongSwan is basically a keying daemon, which uses the Internet Key Exchange protocols (IKEv1 and IKEv2)
to establish security associations (SA) between two peers. IKE provides strong authentication of both peers and derives
unique cryptographic 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 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 actually consist of two components, the actual IPsec SA describing the algorithms and keys used to encrypt
and authenticate the traffic and the policies that define which network traffic shall use such an SA. The policies work
both ways, that is, only traffic matching an inbound policy will be allowed after decryption.

The actual IPsec traffic is not handled by strongSwan but instead by the network and IPsec stack of the operating
system kernel.

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/24 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 wont 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/24 would be a possible solution to this issue.

More information about IPsec and IKE can be found on our wiki.

Authentication Basics¶

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: This uses RSA or ECDSA X.509 certificates 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.
  • Certificate Revocation Lists (CRLs) or the Online Certificate Status Protocol (OCSP) may be
    used to verify the validity of certificates.
  • To securely store private keys smart cards may be used via the PKCS#11 plugin.
  • 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 subject or a subjectAltName extension.
• Pre-Shared-Key (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 authentication (EAP-MD5, EAP-MSCHAPv2, EAP-GTC) or on certificates (EAP-TLS),
  some can even tunnel other EAP methods (EAP-TTLS, EAP-PEAP).
  • The actual authentication of users may be delegated to a RADIUS server with the eap-radius plugin.
  • EAP authentication can be used with IKEv2 and for some methods with IKEv1 using the xauth-eap plugin.
• 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 with either certificates or PSK. With IKEv1 hybrid authentication is is, however,
  possible to authenticate the gateway with a certificate and use only XAuth to authenticate the client.

With IKEv2 it is possible to use multiple authentication rounds, for instance, to first authenticate the "machines" with
certificates and then the "user" with an username/password-based authentication scheme (e.g EAP-MSCHAPv2). It is also
possible to use asymmetric authentication, for instance, by authenticating the gateway with a certificate and the client
with an username/password-based EAP method (in the first authentication round).

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

Configuration Files¶

The configuration files used by strongSwan are as follows:

• ipsec.conf: provides the configuration of IPsec connections
• ipsec.secrets: lists the secrets (pre-shared keys, private keys)
• ipsec.d: stores certificates and private keys
• strongswan.conf: allows one to configure global settings

Terminology¶

left and right as used in the ipsec.conf file denote the two endpoints of an IKE_SA:

• left means the local peer, i.e. the one on which the config file is stored
• right then is the remote peer

You can easily remember this by looking at the first letter of the two terms (left=local, right=remote).

Other Configuration Sources¶

Since 5.2.0 the vici plugin provides a new configuration backend. The configuration is stored in swanctl.conf
and the swanctl directory.

The configuration may also be loaded from an SQL database or provided by custom plugins like the one used with
the NetworkManager plugin.

Installation¶

The installation of strongSwan is covered in a separate part of the wiki.

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.

Invocation and Maintenance¶

strongSwan is usually controlled with the ipsec command. ipsec start will start the starter daemon which in turn
starts and configures the keying daemon charon.

Connections defined as conn sections in ipsec.conf can be started on three different occasions:

• On startup: Connections configured with auto=start will automatically be established when the daemon is started.
• On traffic: If auto=route is used, IPsec policies for the configured traffic (left|rightsubnet) will be installed and traffic
  matching these policies will trigger events that cause the daemon to establish the connection.
• Manually: A connection that uses auto=add has to be established manually with ipsec up <name>. It is also
  possible to use ipsec route <name> to install policies manually for such connections.

After an SA has been established ipsec down may be used to tear down the IKE_SA or individual CHILD_SAs.

Whenever the ipsec.conf file is changed it may be reloaded with ipsec update or ipsec reload. Already established
connections are not affected by these commands, if that is required ipsec restart must be used.

If ipsec.secrets or the files in ipsec.d have been changed the ipsec reread... commands may be used to reload these files.
End-entity certificates placed in ipsec.d/certs are not reloaded automatically, instead they are loaded whenever referenced
with left|rightcert in a conn section. Using the ipsec purge... commands may be required in order for the new files to be used.

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

Logging and Monitoring¶

If you run into problems, increasing the log level might help you understand what exactly went wrong. The different
logging options are described on our wiki and the strongswan.conf man page.

Whenever you encounter a log message similar to "received ... error notify", where ... is, for instance,
NO_PROPOSAL_CHOSEN or TS_UNACCEPTABLE, you should consult the logs of the remote peer so as to find out why
it generated that error notify in the first place.

Starting the daemon with ipsec start --nofork prevents it from forking and will log directly to the console (in case
loggers are configured in strongswan.conf make sure one of them logs to stderr or stdout).

The ipsec status and statusall 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).

PKI¶

To use certificate based authentication you'll need to create either self-signed certificates or setup a whole public-key
infrastructure (PKI), consisting of a Certificate Authority (CA), optional intermediate CAs and end-entity certificates plus
certificate revocation lists (CRL) or other methods like OCSP to verify the validity of certificates.

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

OpenSSL is also a widespread alternative to generate certificates, as are several GUI based CA management utilities.
Commercial CA management tools like Microsoft's are also often used for large scale CAs.

Remote Access Configurations¶

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 right=%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 and optionally the dhcp plugins).

Whether roadwarriors will send all traffic to the gateway or use split-tunneling, that is, only send traffic for specific
destinations through the tunnel, is also something to consider. It is explained more detailed in Forwarding and
Split-Tunneling.

The above page also explains how traffic is forwarded to hosts behind the gateway.

IKEv2 (Windows 7/8, Linux, Android 4+, Mac OS X, iOS 8+)¶

The gateway configurations shown in the Windows 7 section of the wiki may be used for all IKEv2 clients. In both use
cases presented there the gateway is authenticated with a certificate, while the clients will either authenticate themselves
with certificates, or use username and password. Both configurations may be implemented on a gateway to leave it to the
clients to select an authentication method.

With the eap-radius plugin the user authentication may be delegated to a RADIUS server (e.g. an existing Active Directory DC).

Both the strongSwan VPN Client for Android 4 and newer and the strongSwan NetworkManager plugin may be
used with either of these configs.

For Linux roadwarriors that don't want or can't use the NetworkManager plugin this client config may be used.
Alternatively, the charon-cmd command line IKE client provides a simple means to establish roadwarrior connections since 5.1.0.

Our app for Mac OS X supports IKEv2 and simple EAP authentication.

With iOS 8 and Mac OS X 10.10 (Yosemite) Apple introduced support for IKEv2 in their clients. A GUI to configure such connections
is currently not provided, so it's necessary to write (or generate) custom configuration profiles.

IKEv1 (iOS, Mac OS X, Android, Windows)¶

The configuration presented on the iOS and Mac OS X page should work for all IKEv1 clients that support XAuth.

For Windows hosts before Windows 7 it is recommended to use a third-party IPsec client like Shrew instead of the
built-in IKEv1/L2TP client.

Instead of generating a private key and certificate pair for each client you may also use the same key/certificate pair for
all clients. The actual client authentication will then be based on XAuth (this is similar to hybrid authentication, but also works
for clients that don't support it, or implement it incorrectly, like some iOS versions did). Even though the private key/certificate
pair is "public", this still ensures proper authentication of the gateway, but might simplify deployment to clients.

XAuth with PSK may also be used (see #218) but is not recommended for larger deployments.

The XAuth credentials provided by the clients may be verified against the same RADIUS server used for IKEv2 clients with
the help of the xauth-eap plugin.

Site-to-Site Configurations¶

For site-to-site connections you may refer to any of the net2net scenarios (and many others) of our test suite.

The most important difference compared to the remote access case is that the initiator will not request a virtual IP address
but instead use leftsubnet to tunnel traffic from one or more local subnets. For IKEv2 multiple subnets (in CIDR notation) can
be added to left|rightsubnet, separated by commas. If IKEv1 is used a separate conn section has to be added for each
combination of left and right subnet as only the first subnet in left|rightsubnet will be used (using either conn %default or the
also keyword can reduce each of these configs to a few lines).

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 left|rightsubnet
or add a specific host-to-host config.

Host-to-Host Configurations¶

Host-to-host connections are very easy to setup. You basically have to configure right to the hostname or IP address of the peer
and configure the desired authentication, neither leftsubnet nor rightsubnet have to be set explicitly.

Again, our test suite provides several examples.