Project

General

Profile

Introduction to strongSwan » History » Version 3

Tobias Brunner, 21.10.2013 16:24

1 2 Tobias Brunner
{{title(Introduction to strongSwan)}}
2 2 Tobias Brunner
3 1 Tobias Brunner
h1. Introduction to strongSwan
4 1 Tobias Brunner
5 1 Tobias Brunner
{{>toc}}
6 1 Tobias Brunner
7 1 Tobias Brunner
This document is intended to give an introduction to strongSwan for new users (or existing users with catching-up to do).
8 1 Tobias Brunner
9 1 Tobias Brunner
h2. Prerequisites
10 1 Tobias Brunner
11 1 Tobias Brunner
It is assumed that the reader of this document...
12 1 Tobias Brunner
* understands the principles of networking, from setting IP addresses and DNS servers to basic firewalling
13 1 Tobias Brunner
* grasps the basic concepts of authentication based on public-key cryptography and a public-key infrastructure (PKI)
14 1 Tobias Brunner
* knows how to install binary software packages or how to compile source code following instructions
15 1 Tobias Brunner
* is adept on the console
16 1 Tobias Brunner
17 1 Tobias Brunner
If you don't have such knowledge, there exist many ready-to-use appliances that provide remote IPsec access.
18 1 Tobias Brunner
One such device is the "revobox":http://www.revosec.ch/en/products by "revosec":http://www.revosec.ch that is based on strongSwan.
19 1 Tobias Brunner
20 1 Tobias Brunner
h2. Securing a Network
21 1 Tobias Brunner
22 1 Tobias Brunner
strongSwan is a complete IPsec solution providing encryption and authentication to servers and clients.
23 1 Tobias Brunner
It can be used to secure communications with remote networks, so that connecting remotely is the same as
24 1 Tobias Brunner
connecting locally.
25 1 Tobias Brunner
26 1 Tobias Brunner
27 1 Tobias Brunner
!http://www.strongswan.org/uml/testresults/images/a-m-c-w-s-b-med.png!
28 1 Tobias Brunner
29 1 Tobias Brunner
* *Gateway*: The gateway is usually your firewall, but this can be any host within your network.
30 1 Tobias Brunner
Often the gateway is also able to serve a small network with DHCP and DNS.
31 1 Tobias Brunner
In the image above the hosts *moon* and *sun* serve as gateways for the internal hosts *alice* and *bob*,
32 1 Tobias Brunner
respectively.
33 1 Tobias Brunner
* *Remote access / Roadwarrior clients*: Usually, roadwarriors are laptops and other mobile devices
34 1 Tobias Brunner
connecting from remote to your network using the gateway. In the image above *carol* represents a
35 1 Tobias Brunner
roadwarrior who wants to access either of the two networks behind the two gateways.
36 1 Tobias Brunner
* *Remote hosts / Host-to-Host*: This can be a remote web server or a backup system. This is illustrated
37 1 Tobias Brunner
in the image by host *winnetou* and either of the gateways. The connection between the two hosts can
38 1 Tobias Brunner
usually be initiated by either one of them.
39 1 Tobias Brunner
* *Remote sites / Site-to-Site*: Hosts in two or more subnets at different locations should be able to access
40 1 Tobias Brunner
each other. Again referring to the image above, the two subnets @10.1.0.0/24@ and @10.2.0.0/24@ behind
41 1 Tobias Brunner
gateways *moon* and *sun*, respectively, might be connected, so that the hosts *alice* and *bob* may securely
42 1 Tobias Brunner
communicate with one another.
43 1 Tobias Brunner
44 1 Tobias Brunner
On our website you'll find dozens of [[ConfigurationExamples|complete configuration examples]] covering these and similar situations.
45 1 Tobias Brunner
46 1 Tobias Brunner
h2. IKE and IPsec Basics
47 1 Tobias Brunner
48 1 Tobias Brunner
*strongSwan is basically a keying daemon*, which uses the "Internet Key Exchange":http://en.wikipedia.org/wiki/Internet_Key_Exchange protocols (IKEv1 and IKEv2)
49 1 Tobias Brunner
to establish _security associations_ (SA) between two peers. IKE provides strong authentication of both peers and derives
50 1 Tobias Brunner
unique cryptographic session keys.  Such an IKE session is often denoted *IKE_SA* in our documentation.
51 1 Tobias Brunner
Besides authentication and key material IKE also provides the means to exchange configuration information and
52 1 Tobias Brunner
to negotiate IPsec SAs, which are often called *CHILD_SAs*.  IPsec SAs define which network traffic is to be secured
53 1 Tobias Brunner
and how it has to be encrypted and authenticated.
54 1 Tobias Brunner
55 1 Tobias Brunner
A CHILD_SA actually consist of two components, the actual IPsec SA describing the algorithms and keys used to encrypt
56 1 Tobias Brunner
and authenticate the traffic and the policies that define which network traffic shall use such an SA.  The policies work
57 1 Tobias Brunner
both ways, that is, only traffic matching an inbound policy will be allowed after decryption.
58 1 Tobias Brunner
59 1 Tobias Brunner
The actual *IPsec traffic is not handled by strongSwan* but instead by the network and IPsec stack of the operating
60 1 Tobias Brunner
system kernel.
61 1 Tobias Brunner
62 1 Tobias Brunner
The mentioned distinction between policies and SAs often leads to *misconceptions*.  For instance, referring to the image
63 1 Tobias Brunner
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),
64 1 Tobias Brunner
and host carol has a roadwarrior connection to host sun (from which carol received a virtual IP address of 10.3.0.10),
65 1 Tobias Brunner
then carol wont be able to automatically communicate with alice, even if forwarding is enabled on sun.  This is because
66 1 Tobias Brunner
there is no IPsec policy allowing traffic between carol (10.3.0.10) and alice (10.1.0.10). An additional SA between moon
67 1 Tobias Brunner
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.
68 1 Tobias Brunner
69 1 Tobias Brunner
[[IPsecDocumentation|More information about IPsec and IKE]] can be found on our wiki.
70 1 Tobias Brunner
71 1 Tobias Brunner
h2. Authentication Basics
72 1 Tobias Brunner
73 1 Tobias Brunner
To ensure that the peer with which an IKE_SA is established is really who it claims to be it has to be authenticated.
74 1 Tobias Brunner
75 1 Tobias Brunner
strongSwan provides several methods to do this:
76 1 Tobias Brunner
77 1 Tobias Brunner
* *Public Key Authentication*: This uses *RSA or ECDSA X.509 certificates* to verify the authenticity of the peer.
78 1 Tobias Brunner
** Certificates can be self-signed, in which case they have to be installed on all peers, or signed by a common
79 1 Tobias Brunner
Certificate Authority (CA). The latter simplifies deployment and configuration a lot as the gateway only
80 1 Tobias Brunner
needs the CA certificate to authenticate all peers that provide a valid certificate signed by that CA.
81 1 Tobias Brunner
** "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
82 1 Tobias Brunner
used to verify the validity of certificates.
83 1 Tobias Brunner
** To securely store private keys [[SmartCards|smart cards]] may be used via the [[PKCS11Plugin|PKCS#11 plugin]].
84 1 Tobias Brunner
** 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
85 1 Tobias Brunner
the certificate, either by the _subject_ or a _subjectAltName_ extension.
86 1 Tobias Brunner
* *Pre-Shared-Key (PSK)*: A pre-shared-key is an easy to deploy option but it *requires strong secrets* to be secure.
87 1 Tobias Brunner
** If the PSK is known to many users (which is often the case with IKEv1 XAuth with PSK) any user who knows
88 1 Tobias Brunner
the secret could impersonate the gateway. Therefore this method is *not recommended* for large scale
89 1 Tobias Brunner
deployments.
90 1 Tobias Brunner
* *Extensible Authentication Protocol (EAP)*: This covers several possible authentication methods, some are
91 1 Tobias Brunner
based on username/password authentication (EAP-MD5, EAP-MSCHAPv2, EAP-GTC) or on certificates (EAP-TLS),
92 1 Tobias Brunner
some can even tunnel other EAP methods (EAP-TTLS, EAP-PEAP).
93 1 Tobias Brunner
** The actual authentication of users may be delegated to a RADIUS server with the [[EAPRAdius|eap-radius plugin]].
94 1 Tobias Brunner
** EAP authentication can be used with IKEv2 and for some methods with IKEv1 using the [[XAuthEap|xauth-eap plugin]].
95 1 Tobias Brunner
* *eXtended Authentication (XAuth)*: XAuth provides a flexible authentication framework within IKEv1. It is mainly
96 1 Tobias Brunner
used for username/password based authentication. Also, it is generally used as a second authentication method
97 1 Tobias Brunner
after a mutual authentication with either certificates or PSK. With _IKEv1 hybrid authentication_ is is, however,
98 1 Tobias Brunner
possible to authenticate the gateway with a certificate and use only XAuth to authenticate the client.
99 1 Tobias Brunner
100 1 Tobias Brunner
With IKEv2 it is possible to use multiple authentication rounds, for instance, to first authenticate the "machines" with
101 1 Tobias Brunner
certificates and then the "user" with an username/password-based authentication scheme (e.g EAP-MSCHAPv2).  It is also
102 1 Tobias Brunner
possible to use asymmetric authentication, for instance, by authenticating the gateway with a certificate and the client
103 1 Tobias Brunner
with an username/password-based EAP method (in the first authentication round).
104 1 Tobias Brunner
105 1 Tobias Brunner
Again, our website provides dozens of [[ConfigurationExamples|configuration examples]] covering these and other authentication options.
106 1 Tobias Brunner
107 1 Tobias Brunner
h2. Configuration Files
108 1 Tobias Brunner
109 1 Tobias Brunner
The configuration files used by strongSwan are as follows:
110 1 Tobias Brunner
111 1 Tobias Brunner
* [[IpsecConf|ipsec.conf]]: provides the configuration of IPsec connections
112 1 Tobias Brunner
* [[IpsecSecrets|ipsec.secrets]]: lists the secrets (pre-shared keys, private keys)
113 1 Tobias Brunner
* [[IpsecDirectory|ipsec.d]]: stores certificates and private keys
114 1 Tobias Brunner
* [[strongswanConf|strongswan.conf]]: allows one to configure global settings
115 1 Tobias Brunner
116 1 Tobias Brunner
h3. Terminology
117 1 Tobias Brunner
118 1 Tobias Brunner
*left* and *right* as used in the [[ipsec.conf]] file denote the two endpoints of an IKE_SA:
119 1 Tobias Brunner
* *left* means the *local* peer, i.e. the one on which the config file is stored
120 1 Tobias Brunner
* *right* then is the *remote* peer
121 1 Tobias Brunner
122 1 Tobias Brunner
You can easily remember this by looking at the first letter of the two terms (*left=local*, *right=remote*).
123 1 Tobias Brunner
124 1 Tobias Brunner
h3. Other Configuration Sources
125 1 Tobias Brunner
126 1 Tobias Brunner
The configuration may also be loaded from [[SQL|an SQL database]] or provided by custom plugins like the one used with
127 1 Tobias Brunner
the [[NetworkManager|NetworkManager plugin]].
128 1 Tobias Brunner
129 1 Tobias Brunner
130 1 Tobias Brunner
h2. Installation
131 1 Tobias Brunner
132 1 Tobias Brunner
The [[InstallationDocumentation|installation of strongSwan]] is covered in a separate part of the wiki.
133 1 Tobias Brunner
134 1 Tobias Brunner
Using binary packages provided by your distribution is generally recommended as it makes maintenance easier.
135 1 Tobias Brunner
Unfortunately, this means that you are often not able to use the most recent version.
136 1 Tobias Brunner
137 1 Tobias Brunner
138 1 Tobias Brunner
h2. Invocation and Maintenance
139 1 Tobias Brunner
140 1 Tobias Brunner
strongSwan is usually controlled with the [[IpsecCommand|ipsec command]]. @ipsec start@ will start the [[IpsecStarter|starter daemon]] which in turn
141 1 Tobias Brunner
starts and configures the keying daemon [[charon]].
142 1 Tobias Brunner
143 1 Tobias Brunner
Connections defined as [[ConnSection|conn sections in ipsec.conf]] can be started on three different occasions:
144 1 Tobias Brunner
145 1 Tobias Brunner
* *On startup*: Connections configured with _auto=start_ will automatically be established when the daemon is started.
146 1 Tobias Brunner
* *On traffic*: If _auto=route_ is used, IPsec policies for the configured traffic (_left|rightsubnet_) will be installed and traffic
147 1 Tobias Brunner
matching these policies will trigger events that cause the daemon to establish the connection.
148 1 Tobias Brunner
* *Manually*: A connection that uses _auto=add_ has to be established manually with @ipsec up <name>@. It is also
149 1 Tobias Brunner
possible to use @ipsec route <name>@ to install policies manually for such connections.
150 1 Tobias Brunner
151 1 Tobias Brunner
After an SA has been established @ipsec down@ may be used to tear down the IKE_SA or individual CHILD_SAs.
152 1 Tobias Brunner
153 1 Tobias Brunner
Whenever the [[ipsec.conf]] file is changed it may be reloaded with @ipsec update@ or @ipsec reload@. Already established
154 1 Tobias Brunner
connections are not affected by these commands, if that is required @ipsec restart@ must be used.
155 1 Tobias Brunner
156 1 Tobias Brunner
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.
157 1 Tobias Brunner
End-entity certificates placed in [[IpsecDirectoryCerts|ipsec.d/certs]] are not reloaded automatically, instead they are loaded whenever referenced
158 1 Tobias Brunner
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.
159 1 Tobias Brunner
160 1 Tobias Brunner
Using the [[Ipseccommand#List-Commands|ipsec list...]] commands will provide information about loaded or cached certificates, supported algorithms and
161 1 Tobias Brunner
loaded plugins.
162 1 Tobias Brunner
163 1 Tobias Brunner
164 1 Tobias Brunner
h2. Logging and Monitoring
165 1 Tobias Brunner
166 1 Tobias Brunner
If you run into problems, increasing the log level might help you understand what exactly went wrong. The different
167 1 Tobias Brunner
[[Loggerconfiguration|logging options]] are described on our wiki and the [[strongswan.conf]] man page.
168 1 Tobias Brunner
169 1 Tobias Brunner
Whenever you encounter a log message similar to @"received ... error notify"@, where @...@ is, for instance,
170 1 Tobias Brunner
@NO_PROPOSAL_CHOSEN@ or @TS_UNACCEPTABLE@, you should consult the logs of the *remote peer* so as to find out why
171 1 Tobias Brunner
it generated that error notify in the first place.
172 1 Tobias Brunner
173 1 Tobias Brunner
Starting the daemon with @ipsec start --nofork@ prevents it from forking and will log directly to the console (in case
174 1 Tobias Brunner
loggers are configured in [[strongswan.conf]] make sure one of them logs to _stderr_ or _stdout_).
175 1 Tobias Brunner
176 1 Tobias Brunner
The [[IpsecCommand|ipsec]] @status@ and @statusall@ commands will provide information about the established and configured connections.
177 1 Tobias Brunner
178 1 Tobias Brunner
On Linux the _iproute2_ package provides the @ip xfrm state@ and @ip xfrm policy@ commands to request detailed
179 1 Tobias Brunner
information about the IPsec SAs and policies installed in the kernel.  Adding the @-s@ option will display extensive
180 1 Tobias Brunner
statistical information like the number of transmitted or invalid packages. On other platforms the _setkey_ command
181 1 Tobias Brunner
from the _ipsec-tools_ package provides similar information.
182 1 Tobias Brunner
183 1 Tobias Brunner
_tcpdump_ and _wireshark_ are also often useful to debug problems.
184 1 Tobias Brunner
185 1 Tobias Brunner
When testing a connection with _ping_ make sure to select a source IP address (with the @-I@ option) that is included in the
186 1 Tobias Brunner
local traffic selector (also see [[IntroductionToStrongswan#Site-to-Site-Configurations|Site-to-Site Configurations]] below).
187 1 Tobias Brunner
188 1 Tobias Brunner
189 1 Tobias Brunner
h2. PKI
190 1 Tobias Brunner
191 1 Tobias Brunner
To use certificate based authentication you'll need to create either self-signed certificates or setup a whole public-key
192 1 Tobias Brunner
infrastructure (PKI), consisting of a Certificate Authority (CA), optional intermediate CAs and end-entity certificates plus
193 1 Tobias Brunner
certificate revocation lists (CRL) or other methods like OCSP to verify the validity of certificates.
194 1 Tobias Brunner
195 1 Tobias Brunner
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
196 1 Tobias Brunner
complex, we only [[SimpleCA|provide instructions]] to get you started.
197 1 Tobias Brunner
198 1 Tobias Brunner
OpenSSL is also a widespread alternative to generate certificates, as are several GUI based [[CAmanagementGUIs|CA management utilities]].
199 1 Tobias Brunner
Commercial CA management tools like Microsoft's are also often used for large scale CAs.
200 1 Tobias Brunner
201 1 Tobias Brunner
202 1 Tobias Brunner
h2. Remote Access Configurations
203 1 Tobias Brunner
204 1 Tobias Brunner
In this section we present example configurations for common remote access use cases.  In these so called _roadwarrior_
205 1 Tobias Brunner
scenarios mobile clients will be able to connect to a remote network.
206 1 Tobias Brunner
207 1 Tobias Brunner
Because these clients most likely connect from unknown IP addresses the gateway will use _right=%any_ to literally accept
208 1 Tobias Brunner
connections from anywhere.  To simplify [[ForwardingAndSplitTunneling|routing traffic back]] to the clients and because roadwarriors are often located
209 1 Tobias Brunner
behind one or more NAT devices, the use of [[VirtualIP|virtual IP addresses]] is necessary.
210 1 Tobias Brunner
211 1 Tobias Brunner
The virtual IPs can either be from a distinct subnet or actually from the subnet behind the gateway (by use of the
212 1 Tobias Brunner
[[farpplugin|farp]] and optionally the [[dhcpplugin|dhcp]] plugins).
213 1 Tobias Brunner
214 1 Tobias Brunner
Whether roadwarriors will send all traffic to the gateway or use [[ForwardingAndSplitTunneling|split-tunneling]], that is, only send traffic for specific
215 1 Tobias Brunner
destinations through the tunnel, is also something to consider.  It is explained more detailed in [[ForwardingAndSplitTunneling|Forwarding and]]
216 1 Tobias Brunner
[[ForwardingAndSplitTunneling|Split-Tunneling]].
217 1 Tobias Brunner
218 1 Tobias Brunner
The above page also explains how traffic is [[ForwardingAndSplitTunneling|forwarded]] to hosts behind the gateway.
219 1 Tobias Brunner
220 3 Tobias Brunner
h3. IKEv2 (Windows 7/8, Linux, Android 4+, Mac OS X)
221 1 Tobias Brunner
222 1 Tobias Brunner
The gateway configurations shown in the [[Windows7|Windows 7 section]] of the wiki may be used for all IKEv2 clients. In both use
223 1 Tobias Brunner
cases presented there the gateway is authenticated with a certificate, while the clients will either authenticate themselves
224 1 Tobias Brunner
with certificates, or use username and password. Both configurations may be implemented on a gateway to leave it to the
225 1 Tobias Brunner
clients to select an authentication method.
226 1 Tobias Brunner
227 3 Tobias Brunner
With the [[EAPRadius|eap-radius plugin]] the user authentication may be delegated to a RADIUS server (e.g. an existing Active Directory DC).
228 3 Tobias Brunner
229 1 Tobias Brunner
Both the [[AndroidVPNClient|strongSwan VPN Client for Android 4 and newer]] and the [[NetworkManager|strongSwan NetworkManager plugin]] may be
230 1 Tobias Brunner
used with either of these configs.
231 1 Tobias Brunner
232 3 Tobias Brunner
For Linux roadwarriors that don't want or can't use the NetworkManager plugin [[IKEv2ClientConfig|this client config may be used]]. 
233 3 Tobias Brunner
Alternatively, the [[charon-cmd]] command line IKE client provides a simple means to establish roadwarrior connections since version:5.1.0.
234 1 Tobias Brunner
235 3 Tobias Brunner
[[MacOSX#Native-application|Our app for Mac OS X]] supports IKEv2 and simple EAP authentication.
236 1 Tobias Brunner
237 1 Tobias Brunner
h3. IKEv1 (iOS, Mac OS X, Android, Windows)
238 1 Tobias Brunner
239 1 Tobias Brunner
The configuration presented on the [[iOS_(Apple)|iOS and Mac OS X page]] should work for all IKEv1 clients that support XAuth.
240 1 Tobias Brunner
241 1 Tobias Brunner
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
242 1 Tobias Brunner
built-in IKEv1/L2TP client.
243 1 Tobias Brunner
244 1 Tobias Brunner
Instead of generating a private key and certificate pair for each client you may also use the same key/certificate pair for
245 1 Tobias Brunner
all clients. The actual client authentication will then be based on XAuth (this is similar to hybrid authentication, but also works
246 1 Tobias Brunner
for clients that don't support it, or implement it incorrectly, like some iOS versions did). Even though the private key/certificate
247 1 Tobias Brunner
pair is "public", this still ensures proper authentication of the gateway, but might simplify deployment to clients.
248 1 Tobias Brunner
249 1 Tobias Brunner
XAuth with PSK may also be used (see #218) but is not recommended for larger deployments.
250 1 Tobias Brunner
251 1 Tobias Brunner
The XAuth credentials provided by the clients may be verified against the same RADIUS server used for IKEv2 clients with
252 1 Tobias Brunner
the help of the [[XAuthEAP|xauth-eap plugin]].
253 1 Tobias Brunner
254 1 Tobias Brunner
255 1 Tobias Brunner
h2. Site-to-Site Configurations
256 1 Tobias Brunner
257 1 Tobias Brunner
For site-to-site connections you may refer to any of the _net2net_ scenarios (and many others) of "our test suite":http://www.strongswan.org/uml/testresults.
258 1 Tobias Brunner
259 1 Tobias Brunner
The most important difference compared to the remote access case is that the initiator will not request a [[VirtualIP|virtual IP address]]
260 1 Tobias Brunner
but instead use _leftsubnet_ to tunnel traffic from one or more local subnets.  For IKEv2 multiple subnets (in CIDR notation) can
261 1 Tobias Brunner
be added to _left|rightsubnet_, separated by commas. If IKEv1 is used a separate [[ConnSection|conn section]] has to be added for each
262 1 Tobias Brunner
combination of left and right subnet as only the first subnet in _left|rightsubnet_ will be used (using either _conn %default_ or the
263 1 Tobias Brunner
_also_ keyword can reduce each of these configs to a few lines).
264 1 Tobias Brunner
265 1 Tobias Brunner
One thing that often confuses users new to IPsec is that testing a net-to-net scenario from either of the gateways often requires
266 1 Tobias Brunner
one to select the source address used specifically (e.g. with @ping -I@) because the external IP of either gateway might not be
267 1 Tobias Brunner
included in the tunneled subnets. If that is something you require either add the external IPs to the list of subnets in _left|rightsubnet_
268 1 Tobias Brunner
or add a specific host-to-host config.
269 1 Tobias Brunner
270 1 Tobias Brunner
h2. Host-to-Host Configurations
271 1 Tobias Brunner
272 1 Tobias Brunner
Host-to-host connections are very easy to setup. You basically have to configure _right_ to the hostname or IP address of the peer
273 1 Tobias Brunner
and configure the desired authentication, neither leftsubnet nor rightsubnet have to be set explicitly.
274 1 Tobias Brunner
275 1 Tobias Brunner
Again, "our test suite":http://www.strongswan.org/uml/testresults provides several examples.