strongSwan

{{title(Introduction to strongSwan)}}

h1. Introduction to strongSwan

{{>toc}}

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

h2. 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.

h2. 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.

!//www.strongswan.org/testing/testresults/images/a-m-c-w-s-b-med.png!

* *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 [[ConfigurationExamples|complete configuration examples]] covering these and similar situations.

h2. IKE and IPsec Basics

*strongSwan is basically a keying daemon*, which uses the "Internet Key Exchange":http://en.wikipedia.org/wiki/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 (e.g. [[virtualIP|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 (there are two, 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 such an SA

The policies work both ways, that is, 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 a matching inbound IPsec policy will be dropped. This is a security feature.

The actual *IPsec traffic is not handled by strongSwan* but instead by 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 API.*

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.

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, by default, installs specific routes to the remote part of the TS (in newer versions of charon (>5.5.0),

routes aren't installed for transport mode CHILD_SAs).

An exception to this is route based IPsec, which 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 policy based IPsec.

[[IPsecDocumentation|More information about IPsec and IKE]] can be found on our wiki.

h2. 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, ECDSA or EdDSA 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":http://en.wikipedia.org/wiki/Certificate_revocation_list (CRLs) or the "Online Certificate Status Protocol":http://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol (OCSP) may be

used to verify the validity of certificates.

** To securely store private keys [[SmartCards|smart cards]] may be used via the [[PKCS11Plugin|PKCS#11 plugin]].

** In order to prevent "man-in-the-middle attacks":http://en.wikipedia.org/wiki/Man-in-the-middle_attack 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 [[EAPRAdius|eap-radius plugin]].

** EAP authentication can only be used with IKEv2 and for some methods with IKEv1 using the [[XAuthEap|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 a username/password-based EAP method (in the first authentication round). Please be aware that not all IKEv2

implementations support this extension ("RFC 4739":https://tools.ietf.org/html/rfc4739).

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

h2. Configuration Files

The recommended way of configuring strongSwan is via the powerful [[vici]] 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 [[SwanctlDirectory|swanctl directory]]. Global strongSwan settings as well as plugin-specific configurations are defined in [[strongswanConf|strongswan.conf]].

Alternatively, the legacy [[Ipsecstroke|ipsec stroke]] interface and its [[IpsecConf|ipsec.conf]] and [[IpsecSecrets|ipsec.secrets]] configuration files may be used.

h3. Other Configuration Sources

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

h2. Installation

The [[InstallationDocumentation|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.

h2. Invocation and Maintenance

strongSwan is usually managed with the [[swanctl]] command, while the IKE daemon [[charon-systemd|charon]] is controlled by @systemd@ on modern distros.

With legacy installations, strongSwan is controlled by the [[IpsecCommand|ipsec command]], where @ipsec start@ will start the [[IpsecStarter|starter daemon]] which in turn

starts and configures the keying daemon [[charon]].

Connections and CHILD_SAs defined in [[swanctl.conf]] (or in [[ConnSection|conn sections in ipsec.conf]]) can be started on three different occasions:

* *On traffic*: If _start_action=trap/auto=route_ is used, IPsec trap policies for the configured traffic (_local|remote_ts/left|rightsubnet_)

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=start_ (or _auto=start_) will 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 

(_dpd_action/dpdaction_ and/or _close_action/closeaction_) to 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|SecurityRecommendations]] to take care of any problems.

* *Manually*: A connection that uses no _start_action_ (or _auto=add_ in ipsec.conf) has to be established manually with @swanctl --initiate@ (or @ipsec up@) or by a peer/roadwarrior.

Depending on the configuration, it is also possible to use @swanctl --install@ (or @ipsec route@) to install policies manually for such connections, like _start_action=trap/auto=route_ would do it on startup.

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

Whenever the [[swanctl.conf]] file or credentials the [[SwanctlDirectory|swanctl directory]] are changed they may be reloaded with the different @--load*@ commands (with [[ipsec.conf]] the @ipsec update@ or @ipsec reload@ commands may be used to reload the config). Already established

connections are not affected by these commands (unless _start_action=start_ is used), if that is required the SAs or even the daemon must be restarted.

For legacy configs, if [[ipsec.secrets]] or the files in [[IpsecDirectory|ipsec.d]] have been changed the [[IpsecCommand#Reread-Commands|ipsec reread...]] commands may be used to reload these files.

End-entity certificates placed in [[IpsecDirectoryCerts|ipsec.d/certs]] are not loaded automatically, instead they are loaded whenever referenced

with _left|rightcert_ in a [[ConnSection|conn section]]. Using the [[IpsecCommand#Purge-Commands|ipsec purge...]] commands may be required in order for the new files to be used (not required when using [[swanctl]] to load credentials).

Using the different @swanctl --list*@ ([[Ipseccommand#List-Commands|ipsec list...]]) commands will provide information about loaded or cached certificates, supported algorithms and loaded plugins.

h2. Logging and Monitoring

If you run into problems, increasing the log level might help you understand what exactly went wrong. The different

[[Loggerconfiguration|logging options]] are described on our wiki and the [[strongswan.conf]] man page (recommended log settings for

debugging problems may be found on [[HelpRequests]]).

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 [[swanctl]] @--list*@ commands (or [[IpsecCommand|ipsec]] @status@ and @statusall@) 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 [[IntroductionToStrongswan#Site-to-Site-Configurations|Site-to-Site Configurations]] below).

h2. 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 [[IPsecPki|ipsec pki]] utility. Since setting up a whole PKI can be quite

complex, we only [[SimpleCA|provide instructions]] to get you started.

OpenSSL is also a widespread alternative to generate certificates, as are several GUI based [[CAmanagementGUIs|CA management utilities]].

Commercial CA management tools like Microsoft's are also often used for large scale CAs.

h3. Certificate requirements

# *The generated leaf (end) certificates need to authenticate the corresponding peer's IKE ID for authentication to succeed.*

# *To authenticate against another instance of strongSwan using a or several certificates (if attribute certificates are used), the certificate must authenticate the ID that the host sends (so Alice tries to authenticate against Bob as Alice (herself), so Alice's certificate has to have at least a SAN field with the correct type (FQDN) and value "Alice" or the _DN_ (not _CN_!) has to be "Alice"*. In other words, you can use the _complete DN_ or _any_ of the _SAN fields' values_ (assuming the type is correct. See [[IntroductionTostrongSwan#Notes-regarding-certificates|Notes regarding certificates]] for details) as an ID.

# Additionally, the certificate has to be trusted by Bob by, for example, it being known beforehand as valid to Bob or the certificate being authenticated/issued by a certificate authority *that Bob trusts*.

# For authentication to succeed, the other peer has to possess the complete chain of the certificate (from root certificate (the root CA) to the leaf certificate (the host's certificate) *with all intermediate certificates* (all intermediate CAs). This is done by sending any intermediate certificates to the remote host.

h3. Notes regarding certificates

Because a foreign root certificate is not automatically trusted, a certificate's root certificate is _not_ sent to another host. That other host already has to have that root certificate available in the first place for authentication to succeed.

A local certificate is only sent to another host if at least one of the following is true:

# You set leftsendcert=always in the conn that is used

# The remote peer requested 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 to its root certificate.

h2. Routing

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 daemon install the routes into any table you like, or you can disable it completely.

For those purposes, 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:

<pre>

10.1.0.0/24 via 10.2.0.1 src 10.2.0.2

</pre>

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, so the IPsec policies match and traffic

from the local machine to the remote subnet will be secured with IPsec.

To avoid conflicts with these routes (especially if [[VirtualIP|virtual IPs]] 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 you run it on a system that receives a lot of routes via dynamic

routing, for example. You can disable it using the _charon.process_route_ setting in [[strongswan.conf]].

If IPv6 is used then make sure to [[IPv6NDP|bypass NDP(Neighbor Discovery Protocol) traffic]] if necessary.

It is possible that you encounter MSS/MTU problems when tunneling traffic. Please refer to [[ForwardingAndSplitTunneling#MTUMSS-issues|Forwarding and Split-Tunneling]]

for details.

h2. 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 [[ForwardingAndSplitTunneling|routing traffic back]] to the clients and because roadwarriors are often located

behind one or more NAT devices, the use of [[VirtualIP|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

[[farpplugin|farp]] and optionally the [[dhcpplugin|dhcp]] plugins).

Whether roadwarriors will send all traffic to the gateway or use [[ForwardingAndSplitTunneling|split-tunneling]], that is, only send traffic for specific

destinations through the tunnel, is also something to consider.  It is explained more detailed in [[ForwardingAndSplitTunneling|Forwarding and]]

[[ForwardingAndSplitTunneling|Split-Tunneling]].

The above page also explains how traffic is [[ForwardingAndSplitTunneling|forwarded]] to hosts behind the gateway.

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

The gateway configurations shown in the [[Windows7|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 [[EAPRadius|eap-radius plugin]] the user authentication may be delegated to a RADIUS server (e.g. an existing Active Directory DC).

Both the [[AndroidVPNClient|strongSwan VPN Client for Android 4 and newer]] and the [[NetworkManager|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 [[IKEv2ClientConfig|this client config may be used]]. 

Alternatively, the [[charon-cmd]] command line IKE client provides a simple means to establish roadwarrior connections since version:5.1.0.

[[MacOSX#Native-application|Our app for Mac OS X]] supports IKEv2 and simple EAP authentication.

With [[AppleIKEv2Profile|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) [[AppleIKEv2Profile|custom configuration profiles]].

h3. IKEv1 (iOS, Mac OS X, Android, Windows)

The configuration presented on the [[iOS_(Apple)|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":http://www.shrew.net 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 [[XAuthEAP|xauth-eap plugin]].

h2. Site-to-Site Configurations

For site-to-site connections you may refer to the [[UsableExamples|configuration examples]]. Out test suites for all features can be found [[ConfigurationExamples|here]].

The most important difference compared to the remote access case is that the initiator will not request a [[VirtualIP|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 [[ConnSection|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.

h2. 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, [[ConfigurationExamples|our test suite]] provides several examples.