]>
Commit | Line | Data |
---|---|---|
891d332b TB |
1 | # strongSwan Configuration # |
2 | ||
3 | ## Overview ## | |
4 | ||
5 | strongSwan is an OpenSource IPsec-based VPN solution. | |
a477d280 TB |
6 | |
7 | This document is just a short introduction, for more detailed information | |
891d332b | 8 | consult the man pages and [**our wiki**](http://wiki.strongswan.org). |
a477d280 | 9 | |
a477d280 | 10 | |
891d332b | 11 | ## Quickstart ## |
a477d280 | 12 | |
891d332b TB |
13 | In the following examples we assume, for reasons of clarity, that **left** |
14 | designates the **local** host and that **right** is the **remote** host. | |
a477d280 | 15 | |
891d332b TB |
16 | Certificates for users, hosts and gateways are issued by a fictitious |
17 | strongSwan CA. How to generate private keys and certificates using OpenSSL or | |
18 | the strongSwan PKI tool will be explained in one of the sections below. | |
19 | The CA certificate `strongswanCert.pem` must be present on all VPN endpoints | |
20 | in order to be able to authenticate the peers. | |
a477d280 TB |
21 | |
22 | ||
891d332b | 23 | ### Site-to-site case ### |
a477d280 | 24 | |
891d332b TB |
25 | In this scenario two security gateways _moon_ and _sun_ will connect the |
26 | two subnets _moon-net_ and _sun-net_ with each other through a VPN tunnel | |
a477d280 TB |
27 | set up between the two gateways: |
28 | ||
29 | 10.1.0.0/16 -- | 192.168.0.1 | === | 192.168.0.2 | -- 10.2.0.0/16 | |
30 | moon-net moon sun sun-net | |
31 | ||
891d332b | 32 | Configuration on gateway _moon_: |
a477d280 TB |
33 | |
34 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
35 | ||
36 | /etc/ipsec.d/certs/moonCert.pem | |
37 | ||
38 | /etc/ipsec.secrets: | |
39 | ||
40 | : RSA moonKey.pem "<optional passphrase>" | |
41 | ||
42 | /etc/ipsec.conf: | |
43 | ||
44 | conn net-net | |
45 | leftsubnet=10.1.0.0/16 | |
46 | leftcert=moonCert.pem | |
47 | right=192.168.0.2 | |
48 | rightsubnet=10.2.0.0/16 | |
49 | rightid="C=CH, O=strongSwan, CN=sun.strongswan.org" | |
50 | auto=start | |
51 | ||
891d332b | 52 | Configuration on gateway _sun_: |
a477d280 TB |
53 | |
54 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
55 | ||
56 | /etc/ipsec.d/certs/sunCert.pem | |
57 | ||
58 | /etc/ipsec.secrets: | |
59 | ||
60 | : RSA sunKey.pem "<optional passphrase>" | |
61 | ||
62 | /etc/ipsec.conf: | |
63 | ||
64 | conn net-net | |
65 | leftsubnet=10.2.0.0/16 | |
66 | leftcert=sunCert.pem | |
67 | right=192.168.0.1 | |
68 | rightsubnet=10.1.0.0/16 | |
69 | rightid="C=CH, O=strongSwan, CN=moon.strongswan.org" | |
70 | auto=start | |
71 | ||
72 | ||
891d332b | 73 | ### Host-to-host case ### |
a477d280 TB |
74 | |
75 | This is a setup between two single hosts which don't have a subnet behind | |
76 | them. Although IPsec transport mode would be sufficient for host-to-host | |
77 | connections we will use the default IPsec tunnel mode. | |
78 | ||
79 | | 192.168.0.1 | === | 192.168.0.2 | | |
80 | moon sun | |
81 | ||
891d332b | 82 | Configuration on host _moon_: |
a477d280 TB |
83 | |
84 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
85 | ||
86 | /etc/ipsec.d/certs/moonCert.pem | |
87 | ||
88 | /etc/ipsec.secrets: | |
89 | ||
90 | : RSA moonKey.pem "<optional passphrase>" | |
91 | ||
92 | /etc/ipsec.conf: | |
93 | ||
94 | conn host-host | |
95 | leftcert=moonCert.pem | |
96 | right=192.168.0.2 | |
97 | rightid="C=CH, O=strongSwan, CN=sun.strongswan.org" | |
98 | auto=start | |
99 | ||
891d332b | 100 | Configuration on host _sun_: |
a477d280 TB |
101 | |
102 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
103 | ||
104 | /etc/ipsec.d/certs/sunCert.pem | |
105 | ||
106 | /etc/ipsec.secrets: | |
107 | ||
108 | : RSA sunKey.pem "<optional passphrase>" | |
109 | ||
110 | /etc/ipsec.conf: | |
111 | ||
112 | conn host-host | |
113 | leftcert=sunCert.pem | |
114 | right=192.168.0.1 | |
115 | rightid="C=CH, O=strongSwan, CN=moon.strongswan.org" | |
116 | auto=start | |
117 | ||
118 | ||
891d332b | 119 | ### Roadwarrior case ### |
a477d280 TB |
120 | |
121 | This is a very common case where a strongSwan gateway serves an arbitrary | |
122 | number of remote VPN clients usually having dynamic IP addresses. | |
123 | ||
124 | 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x | | |
125 | moon-net moon carol | |
126 | ||
891d332b | 127 | Configuration on gateway _moon_: |
a477d280 TB |
128 | |
129 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
130 | ||
131 | /etc/ipsec.d/certs/moonCert.pem | |
132 | ||
133 | /etc/ipsec.secrets: | |
134 | ||
135 | : RSA moonKey.pem "<optional passphrase>" | |
136 | ||
137 | /etc/ipsec.conf: | |
138 | ||
139 | conn rw | |
140 | leftsubnet=10.1.0.0/16 | |
141 | leftcert=moonCert.pem | |
142 | right=%any | |
143 | auto=add | |
144 | ||
891d332b | 145 | Configuration on roadwarrior _carol_: |
a477d280 TB |
146 | |
147 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
148 | ||
149 | /etc/ipsec.d/certs/carolCert.pem | |
150 | ||
151 | /etc/ipsec.secrets: | |
152 | ||
153 | : RSA carolKey.pem "<optional passphrase>" | |
154 | ||
155 | /etc/ipsec.conf: | |
156 | ||
157 | conn home | |
158 | leftcert=carolCert.pem | |
159 | right=192.168.0.1 | |
160 | rightsubnet=10.1.0.0/16 | |
161 | rightid="C=CH, O=strongSwan, CN=moon.strongswan.org" | |
162 | auto=start | |
163 | ||
164 | ||
891d332b | 165 | ### Roadwarrior case with virtual IP ### |
a477d280 TB |
166 | |
167 | Roadwarriors usually have dynamic IP addresses assigned by the ISP they are | |
891d332b TB |
168 | currently attached to. In order to simplify the routing from _moon-net_ back |
169 | to the remote access client _carol_ it would be desirable if the roadwarrior had | |
170 | an inner IP address chosen from a pre-defined pool. | |
a477d280 TB |
171 | |
172 | 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x | -- 10.3.0.1 | |
173 | moon-net moon carol virtual IP | |
174 | ||
175 | In our example the virtual IP address is chosen from the address pool | |
891d332b | 176 | `10.3.0.0/16` which can be configured by adding the parameter |
a477d280 TB |
177 | |
178 | rightsourceip=10.3.0.0/16 | |
179 | ||
891d332b | 180 | to the gateway's `ipsec.conf`. To request an IP address from this pool a |
a477d280 TB |
181 | roadwarrior can use IKEv1 mode config or IKEv2 configuration payloads. |
182 | The configuration for both is the same | |
183 | ||
184 | leftsourceip=%config | |
185 | ||
891d332b | 186 | Configuration on gateway _moon_: |
a477d280 TB |
187 | |
188 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
189 | ||
190 | /etc/ipsec.d/certs/moonCert.pem | |
191 | ||
192 | /etc/ipsec.secrets: | |
193 | ||
194 | : RSA moonKey.pem "<optional passphrase>" | |
195 | ||
196 | /etc/ipsec.conf: | |
197 | ||
198 | conn rw | |
199 | leftsubnet=10.1.0.0/16 | |
200 | leftcert=moonCert.pem | |
201 | right=%any | |
202 | rightsourceip=10.3.0.0/16 | |
203 | auto=add | |
204 | ||
891d332b | 205 | Configuration on roadwarrior _carol_: |
a477d280 TB |
206 | |
207 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
208 | ||
209 | /etc/ipsec.d/certs/carolCert.pem | |
210 | ||
211 | /etc/ipsec.secrets: | |
212 | ||
213 | : RSA carolKey.pem "<optional passphrase>" | |
214 | ||
215 | /etc/ipsec.conf: | |
216 | ||
217 | conn home | |
218 | leftsourceip=%config | |
219 | leftcert=carolCert.pem | |
220 | right=192.168.0.1 | |
221 | rightsubnet=10.1.0.0/16 | |
222 | rightid="C=CH, O=strongSwan, CN=moon.strongswan.org" | |
223 | auto=start | |
224 | ||
225 | ||
891d332b | 226 | ## Generating certificates and CRLs ## |
a477d280 TB |
227 | |
228 | This section is not a full-blown tutorial on how to use OpenSSL or the | |
229 | strongSwan PKI tool. It just lists a few points that are relevant if you want | |
230 | to generate your own certificates and CRLs for use with strongSwan. | |
231 | ||
232 | ||
891d332b | 233 | ### Generating a CA certificate ### |
a477d280 TB |
234 | |
235 | The OpenSSL statement | |
236 | ||
237 | openssl req -x509 -days 1460 -newkey rsa:4096 \ | |
238 | -keyout strongswanKey.pem -out strongswanCert.pem | |
239 | ||
891d332b TB |
240 | creates a 4096 bit RSA private key `strongswanKey.pem` and a self-signed CA |
241 | certificate `strongswanCert.pem` with a validity of 4 years (1460 days). | |
a477d280 TB |
242 | |
243 | openssl x509 -in cert.pem -noout -text | |
244 | ||
891d332b TB |
245 | lists the properties of a X.509 certificate `cert.pem`. It allows you to verify |
246 | whether the configuration defaults in `openssl.cnf` have been inserted | |
247 | correctly. | |
a477d280 TB |
248 | |
249 | If you prefer the CA certificate to be in binary DER format then the following | |
250 | command achieves this transformation: | |
251 | ||
252 | openssl x509 -in strongswanCert.pem -outform DER -out strongswanCert.der | |
253 | ||
254 | The statements | |
255 | ||
256 | ipsec pki --gen -s 4096 > strongswanKey.der | |
257 | ipsec pki --self --ca --lifetime 1460 --in strongswanKey.der \ | |
258 | --dn "C=CH, O=strongSwan, CN=strongSwan Root CA" \ | |
259 | > strongswanCert.der | |
260 | ipsec pki --print --in strongswanCert.der | |
261 | ||
262 | achieve about the same with the strongSwan PKI tool. Unlike OpenSSL the tool | |
891d332b TB |
263 | stores keys and certificates in the binary DER format by default. |
264 | The `--outform` option may be used to write PEM encoded files. | |
a477d280 | 265 | |
891d332b TB |
266 | The directory `/etc/ipsec.d/cacerts` contains all required CA certificates |
267 | either in binary DER or in Base64 PEM format, irrespective of the file suffix | |
268 | the correct format will be determined. | |
a477d280 TB |
269 | |
270 | ||
891d332b | 271 | ### Generating a host or user certificate ### |
a477d280 TB |
272 | |
273 | The OpenSSL statement | |
274 | ||
275 | openssl req -newkey rsa:2048 -keyout hostKey.pem \ | |
276 | -out hostReq.pem | |
277 | ||
891d332b TB |
278 | generates a 2048 bit RSA private key `hostKey.pem` and a certificate request |
279 | `hostReq.pem` which has to be signed by the CA. | |
a477d280 | 280 | |
891d332b TB |
281 | If you want to add a _subjectAltName_ field to the host certificate you must |
282 | edit the OpenSSL configuration file `openssl.cnf` and add the following line in | |
283 | the `[ usr_cert ]` section: | |
a477d280 TB |
284 | |
285 | subjectAltName=DNS:moon.strongswan.org | |
286 | ||
287 | if you want to identify the host by its Fully Qualified Domain Name (FQDN), or | |
288 | ||
289 | subjectAltName=IP:192.168.0.1 | |
290 | ||
891d332b | 291 | if you want the ID to be of type _IPV4_ADDR_. Of course you could include both |
a477d280 TB |
292 | ID types with |
293 | ||
294 | subjectAltName=DNS:moon.strongswan.org,IP:192.168.0.1 | |
295 | ||
296 | but the use of an IP address for the identification of a host should be | |
297 | discouraged anyway. | |
298 | ||
891d332b | 299 | For user certificates the appropriate ID type is _RFC822_ADDR_ which can be |
a477d280 TB |
300 | specified as |
301 | ||
302 | subjectAltName=email:carol@strongswan.org | |
303 | ||
304 | or if the user's e-mail address is part of the subject's distinguished name | |
305 | ||
306 | subjectAltName=email:copy | |
307 | ||
308 | Now the certificate request can be signed by the CA with the command | |
309 | ||
310 | openssl ca -in hostReq.pem -days 730 -out hostCert.pem -notext | |
311 | ||
891d332b TB |
312 | If you omit the `-days` option then the `default_days` value (365 days) |
313 | specified in `openssl.cnf` is used. The `-notext` option avoids that a human | |
314 | readable listing of the certificate is prepended to the Base64 encoded | |
315 | certificate body. | |
a477d280 | 316 | |
891d332b TB |
317 | If you want to use the dynamic CRL fetching feature described in one of the |
318 | following sections then you may include one or several _crlDistributionPoints_ | |
319 | in your end certificates. This can be done in the `[ usr_cert ]` section of the | |
320 | `openssl.cnf` configuration file: | |
a477d280 TB |
321 | |
322 | crlDistributionPoints=@crl_dp | |
323 | ||
324 | [ crl_dp ] | |
325 | ||
326 | URI.1="http://crl.strongswan.org/strongswan.crl" | |
327 | URI.2="ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=strongSwan, | |
328 | c=CH?certificateRevocationList" | |
329 | ||
330 | If you have only a single HTTP distribution point then the short form | |
331 | ||
332 | crlDistributionPoints="URI:http://crl.strongswan.org/strongswan.crl" | |
333 | ||
334 | also works. | |
335 | ||
336 | Again the statements | |
337 | ||
338 | ipsec pki --gen > moonKey.der | |
339 | ipsec pki --pub --in moonKey.der | ipsec pki --issue --lifetime 730 \ | |
340 | --cacert strongswanCert.der --cakey strongswanKey.der \ | |
341 | --dn "C=CH, O=strongSwan, CN=moon.strongswan.org" \ | |
342 | --san moon.strongswan.org --san 192.168.0.1 \ | |
343 | --crl http://crl.strongswan.org/strongswan.crl > moonCert.der | |
344 | ||
891d332b | 345 | do something similar using the strongSwan PKI tool. |
a477d280 TB |
346 | |
347 | Usually, a Windows or Mac OS X (or iOS) based VPN client needs its private key, | |
891d332b TB |
348 | its host or user certificate, and the CA certificate. The most convenient way |
349 | to load this information is to put everything into a PKCS#12 container: | |
a477d280 TB |
350 | |
351 | openssl pkcs12 -export -inkey carolKey.pem \ | |
352 | -in carolCert.pem -name "carol" \ | |
353 | -certfile strongswanCert.pem -caname "strongSwan Root CA" \ | |
354 | -out carolCert.p12 | |
355 | ||
356 | ||
891d332b | 357 | ### Generating a CRL ### |
a477d280 TB |
358 | |
359 | An empty CRL that is signed by the CA can be generated with the command | |
360 | ||
361 | openssl ca -gencrl -crldays 15 -out crl.pem | |
362 | ||
891d332b TB |
363 | If you omit the `-crldays` option then the `default_crl_days` value (30 days) |
364 | specified in `openssl.cnf` is used. | |
a477d280 TB |
365 | |
366 | If you prefer the CRL to be in binary DER format then this conversion | |
367 | can be achieved with | |
368 | ||
369 | openssl crl -in crl.pem -outform DER -out cert.crl | |
370 | ||
891d332b | 371 | The strongSwan PKI tool provides the `--signcrl` command to sign CRLs. |
a477d280 | 372 | |
891d332b TB |
373 | The directory `/etc/ipsec.d/crls` contains all CRLs either in binary DER |
374 | or in Base64 PEM format, irrespective of the file suffix the correct format | |
a477d280 TB |
375 | will be determined. |
376 | ||
377 | ||
891d332b | 378 | ### Revoking a certificate ### |
a477d280 | 379 | |
891d332b | 380 | A specific host certificate stored in the file `host.pem` is revoked with the |
a477d280 TB |
381 | command |
382 | ||
383 | openssl ca -revoke host.pem | |
384 | ||
385 | Next the CRL file must be updated | |
386 | ||
387 | openssl ca -gencrl -crldays 60 -out crl.pem | |
388 | ||
389 | The content of the CRL file can be listed with the command | |
390 | ||
391 | openssl crl -in crl.pem -noout -text | |
392 | ||
891d332b | 393 | in the case of a Base64 CRL, or alternatively for a CRL in DER format |
a477d280 TB |
394 | |
395 | openssl crl -inform DER -in cert.crl -noout -text | |
396 | ||
891d332b TB |
397 | Again the `--signcrl` command of the strongSwan PKI tool may also be used to |
398 | create new CRLs containing additional certificates. | |
a477d280 TB |
399 | |
400 | ||
891d332b | 401 | ## Configuring the connections - ipsec.conf ## |
a477d280 | 402 | |
891d332b | 403 | ### Configuring my side ### |
a477d280 | 404 | |
891d332b | 405 | Usually the **local** side is the same for all connections. Therefore it makes |
a477d280 | 406 | sense to put the definitions characterizing the strongSwan security gateway into |
891d332b TB |
407 | the `conn %default` section of the configuration file `/etc/ipsec.conf`. If we |
408 | assume throughout this document that the strongSwan security gateway is **left** | |
409 | and the peer is **right** then we can write | |
a477d280 | 410 | |
891d332b TB |
411 | conn %default |
412 | leftcert=moonCert.pem | |
413 | # load connection definitions automatically | |
414 | auto=add | |
a477d280 TB |
415 | |
416 | The X.509 certificate by which the strongSwan security gateway will authenticate | |
417 | itself by sending it in binary form to its peers as part of the Internet Key | |
418 | Exchange (IKE) is specified in the line | |
419 | ||
420 | leftcert=moonCert.pem | |
421 | ||
891d332b | 422 | The certificate can either be stored in Base64 PEM-format or in the binary |
a477d280 | 423 | DER-format. Irrespective of the file suffix the correct format will be |
891d332b | 424 | determined. Therefore `leftcert=moonCert.der` or `leftcert=moonCert.cer` |
a477d280 TB |
425 | would also be valid alternatives. |
426 | ||
427 | When using relative pathnames as in the examples above, the certificate files | |
891d332b TB |
428 | must be stored in in the directory `/etc/ipsec.d/certs`. In order to |
429 | distinguish strongSwan's own certificates from locally stored trusted peer | |
430 | certificates (see below for details), they could also be stored in a | |
431 | subdirectory below `/etc/ipsec.d/certs` as e.g. in | |
a477d280 TB |
432 | |
433 | leftcert=mycerts/moonCert.pem | |
434 | ||
435 | Absolute pathnames are also possible as in | |
436 | ||
437 | leftcert=/usr/ssl/certs/moonCert.pem | |
438 | ||
439 | As an ID for the VPN gateway we recommend the use of a Fully Qualified Domain | |
440 | Name (FQDN) of the form | |
441 | ||
891d332b TB |
442 | conn rw |
443 | right=%any | |
444 | leftid=moon.strongswan.org | |
a477d280 | 445 | |
891d332b TB |
446 | **Important**: When a FQDN identifier is used it must be explicitly included as |
447 | a so called _subjectAltName_ of type _dnsName_ (`DNS:`) in the certificate | |
448 | indicated by `leftcert`. For details on how to generate certificates with | |
449 | _subjectAltNames_, please refer to the sections above. | |
a477d280 | 450 | |
891d332b TB |
451 | If you don't want to mess with _subjectAltNames_, you can use the certificate's |
452 | Distinguished Name (DN) instead, which is an identifier of type _DER_ASN1_DN_ | |
a477d280 TB |
453 | and which can be written e.g. in the LDAP-type format |
454 | ||
891d332b TB |
455 | conn rw |
456 | right=%any | |
457 | leftid="C=CH, O=strongSwan, CN=moon.strongswan.org" | |
a477d280 | 458 | |
891d332b | 459 | Since the subject's DN is part of the certificate, the `leftid` does not have to |
a477d280 TB |
460 | be declared explicitly. Thus the entry |
461 | ||
891d332b TB |
462 | conn rw |
463 | right=%any | |
a477d280 | 464 | |
891d332b | 465 | automatically assumes the subject DN of `leftcert` to be the host ID. |
a477d280 TB |
466 | |
467 | ||
891d332b | 468 | ### Multiple certificates ### |
a477d280 TB |
469 | |
470 | strongSwan supports multiple local host certificates and corresponding | |
471 | RSA private keys: | |
472 | ||
891d332b TB |
473 | conn rw1 |
474 | right=%any | |
475 | rightid=peer1.domain1 | |
476 | leftcert=myCert1.pem | |
477 | # leftid is DN of myCert1 | |
a477d280 | 478 | |
891d332b TB |
479 | conn rw2 |
480 | right=%any | |
481 | rightid=peer2.domain2 | |
482 | leftcert=myCert2.pem | |
483 | # leftid is DN of myCert2 | |
a477d280 | 484 | |
891d332b TB |
485 | When _peer1_ initiates a connection then strongSwan will send _myCert1_ and will |
486 | sign with _myKey1_ defined in `/etc/ipsec.secrets` (see below) whereas | |
487 | _myCert2_ and _myKey2_ will be used in a connection setup started from _peer2_. | |
a477d280 TB |
488 | |
489 | ||
891d332b | 490 | ### Configuring the peer side using CA certificates ### |
a477d280 TB |
491 | |
492 | Now we can proceed to define our connections. In many applications we might | |
493 | have dozens of road warriors connecting to a central strongSwan security | |
494 | gateway. The following most simple statement: | |
495 | ||
891d332b TB |
496 | conn rw |
497 | right=%any | |
a477d280 | 498 | |
891d332b TB |
499 | defines the general roadwarrior case. The line `right=%any` literally means |
500 | that any IPsec peer is accepted, regardless of its current IP source address and | |
501 | its ID, as long as the peer presents a valid X.509 certificate signed by a CA | |
502 | the strongSwan security gateway puts explicit trust in. Additionally, the | |
503 | signature during IKE gives proof that the peer is in possession of the private | |
504 | key matching the public key contained in the transmitted certificate. | |
a477d280 TB |
505 | |
506 | The ID by which a peer is identifying itself during IKE can by any of the ID | |
891d332b TB |
507 | types _IPV[46]_ADDR_, _FQDN_, _RFC822_ADDR_ or _DER_ASN1_DN_. If one of the |
508 | first three ID types is used, then the accompanying X.509 certificate of the | |
509 | peer must contain a matching _subjectAltName_ field of the type _ipAddress_ | |
510 | (`IP:`), _dnsName_ (`DNS:`) or _rfc822Name_ (`email:`), respectively. With the | |
511 | fourth type, _DER_ASN1_DN_, the identifier must completely match the subject | |
512 | field of the peer's certificate. One of the two possible representations of a | |
a477d280 TB |
513 | Distinguished Name (DN) is the LDAP-type format |
514 | ||
515 | rightid="C=CH, O=strongSwan IPsec, CN=sun.strongswan.org" | |
516 | ||
517 | Additional whitespace can be added everywhere as desired since it will be | |
891d332b TB |
518 | automatically eliminated by the parser. An exception is the single whitespace |
519 | between individual words, like e.g. in `strongSwan IPsec`, which is preserved. | |
a477d280 TB |
520 | |
521 | The Relative Distinguished Names (RDNs) can alternatively be separated by a | |
891d332b | 522 | slash `/` instead of a comma `,` |
a477d280 TB |
523 | |
524 | rightid="/C=CH/O=strongSwan IPsec/CN=sun.strongswan.org" | |
525 | ||
526 | This is the representation extracted from the certificate by the OpenSSL | |
891d332b | 527 | `-subject` command line option |
a477d280 TB |
528 | |
529 | openssl x509 -in sunCert.pem -noout -subject | |
530 | ||
531 | The following RDNs are supported by strongSwan | |
532 | ||
891d332b TB |
533 | | Name | Description | |
534 | |--------------------|----------------------------------| | |
535 | | DC | Domain Component | | |
536 | | C | Country | | |
537 | | ST | State or province | | |
538 | | L | Locality or town | | |
539 | | O | Organization | | |
540 | | OU | Organizational Unit | | |
541 | | CN | Common Name | | |
542 | | ND | NameDistinguisher, used with CN | | |
543 | | N | Name | | |
544 | | G | Given name | | |
545 | | S | Surname | | |
546 | | I | Initials | | |
547 | | T | Personal title | | |
548 | | E | E-mail | | |
549 | | Email | E-mail | | |
550 | | emailAddress | E-mail | | |
551 | | SN | Serial number | | |
552 | | serialNumber | Serial number | | |
553 | | D | Description | | |
554 | | ID | X.500 Unique Identifier | | |
555 | | UID | User ID | | |
556 | | TCGID | [Siemens] Trust Center Global ID | | |
557 | | UN | Unstructured Name | | |
558 | | unstructuredName | Unstructured Name | | |
559 | | UA | Unstructured Address | | |
560 | | unstructuredAddress| Unstructured Address | | |
561 | | EN | Employee Number | | |
562 | | employeeNumber | Employee Number | | |
563 | | dnQualifier | DN Qualifier | | |
a477d280 TB |
564 | |
565 | With the roadwarrior connection definition listed above, an IPsec SA for | |
891d332b TB |
566 | the strongSwan security gateway `moon.strongswan.org` itself can be established. |
567 | If the roadwarriors should be able to reach e.g. the two subnets `10.1.0.0/24` | |
568 | and `10.1.3.0/24` behind the security gateway then the following connection | |
a477d280 TB |
569 | definitions will make this possible |
570 | ||
891d332b TB |
571 | conn rw1 |
572 | right=%any | |
573 | leftsubnet=10.1.0.0/24 | |
a477d280 | 574 | |
891d332b TB |
575 | conn rw3 |
576 | right=%any | |
577 | leftsubnet=10.1.3.0/24 | |
a477d280 TB |
578 | |
579 | For IKEv2 connections this can even be simplified by using | |
580 | ||
581 | leftsubnet=10.1.0.0/24,10.1.3.0/24 | |
582 | ||
583 | If not all peers in possession of a X.509 certificate signed by a specific | |
584 | certificate authority shall be given access to the Linux security gateway, | |
585 | then either a subset of them can be barred by listing the serial numbers of | |
891d332b TB |
586 | their certificates in a certificate revocation list (CRL) or as an alternative, |
587 | access can be controlled by explicitly putting a roadwarrior entry for each | |
588 | eligible peer into `ipsec.conf`: | |
a477d280 | 589 | |
891d332b TB |
590 | conn sun |
591 | right=%any | |
592 | rightid=sun.strongswan.org | |
a477d280 | 593 | |
891d332b TB |
594 | conn carol |
595 | right=%any | |
596 | rightid=carol@strongswan.org | |
a477d280 | 597 | |
891d332b TB |
598 | conn dave |
599 | right=%any | |
600 | rightid="C=CH, O=strongSwan, CN=dave@strongswan.org" | |
a477d280 TB |
601 | |
602 | When the IP address of a peer is known to be stable, it can be specified as | |
603 | well. This entry is mandatory when the strongSwan host wants to act as the | |
604 | initiator of an IPsec connection. | |
605 | ||
891d332b TB |
606 | conn sun |
607 | right=192.168.0.2 | |
608 | rightid=sun.strongswan.org | |
a477d280 | 609 | |
891d332b TB |
610 | conn carol |
611 | right=192.168.0.100 | |
612 | rightid=carol@strongswan.org | |
a477d280 | 613 | |
891d332b TB |
614 | conn dave |
615 | right=192.168.0.200 | |
616 | rightid="C=CH, O=strongSwan, CN=dave@strongswan.org" | |
a477d280 | 617 | |
891d332b TB |
618 | conn venus |
619 | right=192.168.0.50 | |
a477d280 | 620 | |
891d332b TB |
621 | In the last example the ID types _FQDN_, _RFC822_ADDR_, _DER_ASN1_DN_ and |
622 | _IPV4_ADDR_, respectively, were used. Of course all connection definitions | |
623 | presented so far have included the lines in the `conn %defaults` section, | |
624 | comprising among other a `leftcert` entry. | |
a477d280 TB |
625 | |
626 | ||
891d332b | 627 | ### Handling Virtual IPs and narrowing ### |
a477d280 | 628 | |
891d332b TB |
629 | Often roadwarriors are behind NAT-boxes, which causes the inner IP source |
630 | address of an IPsec tunnel to be different from the outer IP source address | |
631 | usually assigned dynamically by the ISP. Whereas the varying outer IP address | |
632 | can be handled by the `right=%any` construct, the inner IP address or subnet | |
633 | must always be declared in a connection definition. Therefore for the three | |
634 | roadwarriors _rw1_ to _rw3_ connecting to a strongSwan security gateway the | |
635 | following entries are required in `/etc/ipsec.conf`: | |
a477d280 | 636 | |
891d332b TB |
637 | conn rw1 |
638 | right=%any | |
639 | righsubnet=10.4.0.5/32 | |
a477d280 | 640 | |
891d332b TB |
641 | conn rw2 |
642 | right=%any | |
643 | rightsubnet=10.4.0.47/32 | |
a477d280 | 644 | |
891d332b TB |
645 | conn rw3 |
646 | right=%any | |
647 | rightsubnet=10.4.0.128/28 | |
a477d280 TB |
648 | |
649 | Because the charon daemon uses narrowing (even for IKEv1) these three entries | |
650 | can be reduced to the single connection definition | |
651 | ||
891d332b TB |
652 | conn rw |
653 | right=%any | |
654 | rightsubnet=10.4.0.0/24 | |
a477d280 TB |
655 | |
656 | Any host will be accepted (of course after successful authentication based on | |
657 | the peer's X.509 certificate only) if it declares a client subnet lying totally | |
891d332b TB |
658 | within the boundaries defined by the subnet definition (in our example |
659 | `10.4.0.0/24`). | |
a477d280 TB |
660 | |
661 | This strongSwan feature can also be helpful with VPN clients getting a | |
662 | dynamically assigned inner IP from a DHCP server located on the NAT router box. | |
663 | ||
891d332b TB |
664 | Since the private IP address of roadwarriors will often not be known they are |
665 | usually assigned virtual IPs from a predefined pool. This also makes routing | |
666 | traffic back to the roadwarriors easier. For example, to assign each client an | |
667 | IP address from the `10.5.0.0/24` subnet `conn rw` can be defined as | |
a477d280 | 668 | |
891d332b TB |
669 | conn rw |
670 | right=%any | |
671 | rightsourceip=10.5.0.0/24 | |
a477d280 | 672 | |
a477d280 | 673 | |
891d332b | 674 | ### Protocol and Port Selectors ### |
a477d280 | 675 | |
891d332b TB |
676 | strongSwan offers the possibility to restrict the protocol and optionally the |
677 | ports in an IPsec SA using the `rightprotoport` and `leftprotoport` parameters. | |
678 | For IKEv2 multiple such restrictions can also be configured in | |
679 | `leftsubnet` and `rightsubnet`. | |
a477d280 | 680 | |
891d332b | 681 | Some examples: |
a477d280 | 682 | |
891d332b TB |
683 | conn icmp |
684 | right=%any | |
685 | rightprotoport=icmp | |
686 | leftid=moon.strongswan.org | |
687 | leftprotoport=icmp | |
688 | ||
689 | conn http | |
690 | right=%any | |
691 | rightprotoport=6 | |
692 | leftid=moon.strongswan.org | |
693 | leftprotoport=6/80 | |
694 | ||
695 | conn l2tp | |
696 | right=%any | |
697 | # with port wildcard for interoperability with certain L2TP clients | |
698 | rightprotoport=17/%any | |
699 | leftid=moon.strongswan.org | |
700 | leftprotoport=17/1701 | |
701 | ||
702 | conn dhcp | |
703 | right=%any | |
704 | rightprotoport=udp/bootpc | |
705 | leftid=moon.strongswan.org | |
706 | leftsubnet=0.0.0.0/0 #allows DHCP discovery broadcast | |
707 | leftprotoport=udp/bootps | |
a477d280 | 708 | |
891d332b TB |
709 | Protocols and ports can be designated either by their numerical values |
710 | or by their acronyms defined in `/etc/services`. | |
a477d280 TB |
711 | |
712 | Based on the protocol and port selectors appropriate policies will be set | |
713 | up, so that only the specified payload types will pass through the IPsec | |
714 | tunnel. | |
715 | ||
716 | ||
891d332b | 717 | ### IPsec policies based on wildcards ### |
a477d280 TB |
718 | |
719 | In large VPN-based remote access networks there is often a requirement that | |
720 | access to the various parts of an internal network must be granted selectively, | |
721 | e.g. depending on the group membership of the remote access user. strongSwan | |
722 | makes this possible by applying wildcard filtering on the VPN user's | |
891d332b | 723 | distinguished name (_ID_DER_ASN1_DN_). |
a477d280 TB |
724 | |
725 | Let's make a practical example: | |
726 | ||
891d332b TB |
727 | An organization has a sales department (_OU=Sales_) and a research group |
728 | (_OU=Research_). In the company intranet there are separate subnets for Sales | |
729 | (`10.0.0.0/24`) and Research (`10.0.1.0/24`) but both groups share a common web | |
730 | server (`10.0.2.100`). The VPN clients use Virtual IP addresses that are either | |
a477d280 | 731 | assigned statically or from a dynamic pool. The sales and research departments |
891d332b TB |
732 | use IP addresses from separate address pools (`10.1.0.0/24`) and |
733 | (`10.1.1.0/24`), respectively. An X.509 certificate is issued to each employee, | |
734 | containing in its subject distinguished name the country (_C=CH_), the company | |
735 | (_O=ACME_), the group membership (_OU=Sales_ or _OU=Research_) and the common | |
736 | name (e.g. _CN=Bart Simpson_). | |
a477d280 TB |
737 | |
738 | The IPsec policy defined above can now be enforced with the following three | |
739 | IPsec security associations: | |
740 | ||
891d332b TB |
741 | conn sales |
742 | right=%any | |
743 | rightid="C=CH, O=ACME, OU=Sales, CN=*" | |
744 | rightsourceip=10.1.0.0/24 # Sales IP range | |
745 | leftsubnet=10.0.0.0/24 # Sales subnet | |
746 | ||
747 | conn research | |
748 | right=%any | |
749 | rightid="C=CH, O=ACME, OU=Research, CN=*" | |
750 | rightsourceip=10.1.1.0/24 # Research IP range | |
751 | leftsubnet=10.0.1.0/24 # Research subnet | |
752 | ||
753 | conn web | |
754 | right=%any | |
755 | rightid="C=CH, O=ACME, OU=*, CN=*" | |
756 | rightsubnet=10.1.0.0/23 # Remote access IP range | |
757 | leftsubnet=10.0.2.100/32 # Web server | |
758 | rightprotoport=tcp # TCP protocol only | |
759 | leftprotoport=tcp/http # TCP port 80 only | |
760 | ||
761 | The `*` character is used as a wildcard in relative distinguished names (RDNs). | |
762 | In order to match a wildcard template, the _ID_DER_ASN1_DN_ of a peer must | |
763 | contain the same number of RDNs (selected from the list given earlier) appearing | |
764 | in the exact order defined by the template. | |
a477d280 TB |
765 | |
766 | "C=CH, O=ACME, OU=Research, OU=Special Effects, CN=Bart Simpson" | |
767 | ||
768 | matches the templates | |
769 | ||
770 | "C=CH, O=ACME, OU=Research, OU=*, CN=*" | |
a477d280 | 771 | "C=CH, O=ACME, OU=*, OU=Special Effects, CN=*" |
a477d280 TB |
772 | "C=CH, O=ACME, OU=*, OU=*, CN=*" |
773 | ||
774 | but not the template | |
775 | ||
776 | "C=CH, O=ACME, OU=*, CN=*" | |
777 | ||
778 | which doesn't have the same number of RDNs. | |
779 | ||
780 | ||
891d332b | 781 | ### IPsec policies based on CA certificates ### |
a477d280 | 782 | |
891d332b TB |
783 | As an alternative to the wildcard based IPsec policies described above, access |
784 | to specific client host and subnets can be controlled on the basis of the CA | |
785 | that issued the peer certificate | |
a477d280 | 786 | |
891d332b TB |
787 | conn sales |
788 | right=%any | |
789 | rightca="C=CH, O=ACME, OU=Sales, CN=Sales CA" | |
790 | rightsourceip=10.1.0.0/24 # Sales IP range | |
791 | leftsubnet=10.0.0.0/24 # Sales subnet | |
a477d280 | 792 | |
891d332b TB |
793 | conn research |
794 | right=%any | |
795 | rightca="C=CH, O=ACME, OU=Research, CN=Research CA" | |
796 | rightsourceip=10.1.1.0/24 # Research IP range | |
797 | leftsubnet=10.0.1.0/24 # Research subnet | |
a477d280 | 798 | |
891d332b TB |
799 | conn web |
800 | right=%any | |
801 | rightca="C=CH, O=ACME, CN=ACME Root CA" | |
802 | rightsubnet=10.1.0.0/23 # Remote access IP range | |
803 | leftsubnet=10.0.2.100/32 # Web server | |
804 | rightprotoport=tcp # TCP protocol only | |
805 | leftprotoport=tcp/http # TCP port 80 only | |
a477d280 | 806 | |
891d332b | 807 | In the example above, the connection _sales_ can be used by peers |
a477d280 | 808 | presenting certificates issued by the Sales CA, only. In the same way, |
891d332b TB |
809 | the use of the connection _research_ is restricted to owners of certificates |
810 | issued by the Research CA. The connection _web_ is open to both "Sales" and | |
811 | "Research" peers because the required _ACME Root CA_ is the issuer of the | |
812 | Research and Sales intermediate CAs. If no `rightca` parameter is present | |
a477d280 | 813 | then any valid certificate issued by one of the trusted CAs in |
891d332b | 814 | `/etc/ipsec.d/cacerts` can be used by the peer. |
a477d280 | 815 | |
891d332b | 816 | The `leftca` parameter usually doesn't have to be set explicitly because |
a477d280 | 817 | by default it is set to the issuer field of the certificate loaded via |
891d332b | 818 | `leftcert`. The statement |
a477d280 TB |
819 | |
820 | rightca=%same | |
821 | ||
822 | sets the CA requested from the peer to the CA used by the left side itself | |
823 | as e.g. in | |
824 | ||
891d332b TB |
825 | conn sales |
826 | right=%any | |
827 | rightca=%same | |
828 | leftcert=mySalesCert.pem | |
a477d280 TB |
829 | |
830 | ||
891d332b | 831 | ## Configuring certificates and CRLs ## |
a477d280 TB |
832 | |
833 | ||
891d332b | 834 | ### Installing the CA certificates ### |
a477d280 TB |
835 | |
836 | X.509 certificates received by strongSwan during the IKE protocol are | |
837 | automatically authenticated by going up the trust chain until a self-signed | |
838 | root CA certificate is reached. Usually host certificates are directly signed | |
839 | by a root CA, but strongSwan also supports multi-level hierarchies with | |
840 | intermediate CAs in between. All CA certificates belonging to a trust chain | |
891d332b | 841 | must be copied in either binary DER or Base64 PEM format into the directory |
a477d280 TB |
842 | |
843 | /etc/ipsec.d/cacerts/ | |
844 | ||
845 | ||
891d332b | 846 | ### Installing optional certificate revocation lists (CRLs) ### |
a477d280 | 847 | |
891d332b | 848 | By copying a CA certificate into `/etc/ipsec.d/cacerts/`, automatically all user |
a477d280 TB |
849 | or host certificates issued by this CA are declared valid. Unfortunately, |
850 | private keys might get compromised inadvertently or intentionally, personal | |
851 | certificates of users leaving a company have to be blocked immediately, etc. | |
852 | To this purpose certificate revocation lists (CRLs) have been created. CRLs | |
853 | contain the serial numbers of all user or host certificates that have been | |
854 | revoked due to various reasons. | |
855 | ||
856 | After successful verification of the X.509 trust chain, strongSwan searches its | |
891d332b TB |
857 | list of CRLs, either obtained by loading them from the `/etc/ipsec.d/crls/` |
858 | directory, or fetching them dynamically from a HTTP or LDAP server, for the | |
a477d280 TB |
859 | presence of a CRL issued by the CA that has signed the certificate. |
860 | ||
861 | If the serial number of the certificate is found in the CRL then the public key | |
891d332b TB |
862 | contained in the certificate is declared invalid and the IKE SA will not be |
863 | established. If no CRL is found or if the deadline defined in the _nextUpdate_ | |
a477d280 | 864 | field of the CRL has been reached, a warning is issued but the public key will |
891d332b TB |
865 | nevertheless be accepted (this behavior can be changed, see below). CRLs must |
866 | be stored either in binary DER or Base64 PEM format in the `crls` directory. | |
a477d280 TB |
867 | |
868 | ||
891d332b | 869 | ### Dynamic update of certificates and CRLs ### |
a477d280 TB |
870 | |
871 | strongSwan reads certificates and CRLs from their respective files during system | |
872 | startup and keeps them in memory. X.509 certificates have a finite life span | |
873 | defined by their validity field. Therefore it must be possible to replace CA or | |
874 | OCSP certificates kept in system memory without disturbing established IKE SAs. | |
875 | Certificate revocation lists should also be updated in the regular intervals | |
891d332b | 876 | indicated by the _nextUpdate_ field in the CRL body. The following interactive |
a477d280 TB |
877 | commands allow the manual replacement of the various files: |
878 | ||
891d332b TB |
879 | |
880 | | Command | Action | | |
881 | |-------------------------|-------------------------------------------------| | |
882 | | ipsec rereadaacerts | reload all files in `/etc/ipsec.d/aacerts/` | | |
883 | | ipsec rereadacerts | reload all files in `/etc/ipsec.d/acerts/` | | |
884 | | ipsec rereadcacerts | reload all files in `/etc/ipsec.d/cacerts/` | | |
885 | | ipsec rereadcrls | reload all files in `/etc/ipsec.d/crls/` | | |
886 | | ipsec rereadocspcerts | reload all files in `/etc/ipsec.d/ocspcerts/` | | |
887 | | ipsec rereadsecrets | reload `/etc/ipsec.secrets` and configured keys | | |
888 | | ipsec rereadall | all the commands above combined | | |
889 | | ipsec purgecerts | purge all cached certificates | | |
890 | | ipsec purgecrl | purge all cached CRLs | | |
891 | | ipsec purgeocsp | purge the OCSP cache | | |
892 | ||
a477d280 TB |
893 | |
894 | CRLs can also be automatically fetched from an HTTP or LDAP server by using | |
895 | the CRL distribution points contained in X.509 certificates. | |
896 | ||
897 | ||
891d332b | 898 | ### Local caching of CRLs ### |
a477d280 | 899 | |
891d332b | 900 | The `ipsec.conf` option |
a477d280 | 901 | |
891d332b TB |
902 | config setup |
903 | cachecrls=yes | |
a477d280 TB |
904 | |
905 | activates the local caching of CRLs that were dynamically fetched from an | |
891d332b TB |
906 | HTTP or LDAP server. Cached copies are stored in `/etc/ipsec.d/crls` using a |
907 | unique filename formed from the issuer's _subjectKeyIdentifier_ and the | |
908 | suffix `.crl`. | |
a477d280 TB |
909 | |
910 | With the cached copy the CRL is immediately available after startup. When the | |
911 | local copy is about to expire it is automatically replaced with an updated CRL | |
912 | fetched from one of the defined CRL distribution points. | |
913 | ||
914 | ||
891d332b | 915 | ### Online Certificate Status Protocol (OCSP) ### |
a477d280 | 916 | |
891d332b | 917 | The _Online Certificate Status Protocol_ is defined by RFC 2560. It can be |
a477d280 TB |
918 | used to query an OCSP server about the current status of an X.509 certificate |
919 | and is often used as a more dynamic alternative to a static Certificate | |
920 | Revocation List (CRL). Both the OCSP request sent by the client and the OCSP | |
921 | response messages returned by the server are transported via a standard | |
891d332b | 922 | TCP/HTTP connection. |
a477d280 TB |
923 | |
924 | In the simplest OCSP setup, a default URI under which the OCSP server for a | |
891d332b | 925 | given CA can be accessed is defined in `ipsec.conf`: |
a477d280 | 926 | |
891d332b TB |
927 | ca strongswan |
928 | cacert=strongswanCert.pem | |
929 | ocspuri=http://ocsp.strongswan.org:8880 | |
930 | auto=add | |
a477d280 TB |
931 | |
932 | The HTTP port can be freely chosen. | |
933 | ||
934 | OpenSSL implements an OCSP server that can be used in conjunction with an | |
891d332b | 935 | OpenSSL-based Public Key Infrastructure. The OCSP server is started with the |
a477d280 TB |
936 | following command: |
937 | ||
938 | openssl ocsp -index index.txt -CA strongswanCert.pem -port 8880 \ | |
939 | -rkey ocspKey.pem -rsigner ocspCert.pem \ | |
940 | -resp_no_certs -nmin 60 -text | |
941 | ||
942 | The command consists of the parameters | |
943 | ||
891d332b TB |
944 | -index index.txt is a copy of the OpenSSL index file containing the list |
945 | of all issued certificates. The certificate status in index.txt | |
946 | is designated either by V for valid or R for revoked. If a new | |
947 | certificate is added or if a certificate is revoked using the | |
948 | openssl ca command, the OCSP server must be restarted in order for | |
949 | the changes in index.txt to take effect. | |
a477d280 | 950 | |
891d332b | 951 | -CA the CA certificate |
a477d280 | 952 | |
891d332b | 953 | -port the HTTP port the OCSP server is listening on. |
a477d280 | 954 | |
891d332b TB |
955 | -rkey the private key used to sign the OCSP response. The use of the |
956 | sensitive CA private key is not recommended since this could | |
957 | jeopardize the security of your production PKI if the OCSP | |
958 | server is hacked. It is much better to generate a special | |
959 | RSA private key just for OCSP signing use instead. | |
a477d280 | 960 | |
891d332b TB |
961 | -rsigner the certificate of the OCSP server containing a public key which |
962 | matches the private key defined by -rkey and which can be used by | |
963 | the client to check the trustworthiness of the signed OCSP | |
964 | response. | |
a477d280 | 965 | |
891d332b TB |
966 | -resp_no_certs With this option the OCSP signer certificate defined by |
967 | -rsigner is not included in the OCSP response. | |
a477d280 | 968 | |
891d332b | 969 | -nmin the validity interval of an OCSP response given in minutes. |
a477d280 | 970 | |
891d332b TB |
971 | -text this option activates a verbose logging output, showing the |
972 | contents of both the received OCSP request and sent OCSP response. | |
a477d280 TB |
973 | |
974 | ||
975 | The OCSP signer certificate can either be put into the default directory | |
976 | ||
977 | /etc/ipsec.d/ocspcerts | |
978 | ||
979 | or alternatively strongSwan can receive it as part of the OCSP response from the | |
980 | remote OCSP server. In order to verify that the server is indeed authorized by | |
981 | a CA to deal out certificate status information an extended key usage attribute | |
982 | must be included in the OCSP server certificate. Just insert the parameter | |
983 | ||
984 | extendedKeyUsage=OCSPSigner | |
985 | ||
891d332b | 986 | in the `[ usr_cert ]` section of your `openssl.cnf` configuration file before |
a477d280 TB |
987 | the CA signs the OCSP server certificate. |
988 | ||
891d332b | 989 | For a given CA the corresponding _ca_ section in `ipsec.conf` (see below) allows |
a477d280 TB |
990 | to define the URI of a single OCSP server. As an alternative an OCSP URI can be |
991 | embedded into each host and user certificate by putting the line | |
992 | ||
993 | authorityInfoAccess = OCSP;URI:http://ocsp.strongswan.org:8880 | |
994 | ||
891d332b TB |
995 | into the `[ usr_cert ]` section of your `openssl.cnf` configuration file. |
996 | If an OCSP _authorityInfoAccess_ extension is present in a certificate then this | |
a477d280 TB |
997 | record overrides the default URI defined by the ca section. |
998 | ||
999 | ||
891d332b | 1000 | ### CRL Policy ### |
a477d280 TB |
1001 | |
1002 | By default strongSwan is quite tolerant concerning the handling of CRLs. It is | |
891d332b TB |
1003 | not mandatory for a CRL to be present in `/etc/ipsec.d/crls` and if the |
1004 | expiration date defined by the _nextUpdate_ field of a CRL has been reached just | |
1005 | a warning is issued but a peer certificate will always be accepted if it has not | |
1006 | been revoked. | |
a477d280 TB |
1007 | |
1008 | If you want to enforce a stricter CRL policy then you can do this by setting | |
891d332b TB |
1009 | the `strictcrlpolicy` option. This is done in the `config setup` section |
1010 | of the `ipsec.conf` file: | |
a477d280 TB |
1011 | |
1012 | config setup | |
1013 | strictcrlpolicy=yes | |
1014 | ... | |
1015 | ||
1016 | A certificate received from a peer will not be accepted if no corresponding | |
891d332b TB |
1017 | CRL or OCSP response is available. And if an IKE SA re-negotiation takes |
1018 | place after the _nextUpdate_ deadline has been reached, the peer certificate | |
1019 | will be declared invalid and the cached public key will be deleted, causing | |
a477d280 | 1020 | the connection in question to fail. Therefore if you are going to use the |
891d332b TB |
1021 | `strictcrlpolicy=yes` option, make sure that the CRLs will always be updated |
1022 | in time. Otherwise a total standstill might ensue. | |
a477d280 | 1023 | |
891d332b | 1024 | As mentioned earlier the default setting is `strictcrlpolicy=no`. |
a477d280 TB |
1025 | |
1026 | ||
891d332b | 1027 | ### Configuring the peer side using locally stored certificates ### |
a477d280 | 1028 | |
891d332b TB |
1029 | If you don't want to use trust chains based on CA certificates as proposed above |
1030 | you can alternatively import trusted peer certificates directly. | |
a477d280 | 1031 | |
891d332b TB |
1032 | With the `conn %default` section defined above and the use of the `rightcert` |
1033 | keyword for the peer side, the connection definitions presented earlier can | |
1034 | alternatively be written as | |
a477d280 TB |
1035 | |
1036 | conn sun | |
1037 | right=%any | |
891d332b | 1038 | rightid=sun.strongswan.org |
a477d280 TB |
1039 | rightcert=sunCert.cer |
1040 | ||
1041 | conn carol | |
1042 | right=192.168.0.100 | |
1043 | rightcert=carolCert.der | |
1044 | ||
891d332b TB |
1045 | If the peer certificates are loaded locally then there is no need to send any |
1046 | certificates to the other end via the IKE protocol. Especially if self-signed | |
1047 | certificates are used which wouldn't be accepted anyway by the other side. | |
1048 | In these cases it is recommended to add | |
a477d280 TB |
1049 | |
1050 | leftsendcert=never | |
1051 | ||
891d332b | 1052 | to the connection definition(s) in order to avoid the sending of the host's |
a477d280 TB |
1053 | own certificate. The default value is |
1054 | ||
1055 | leftsendcert=ifasked | |
1056 | ||
891d332b TB |
1057 | which causes certificates to only be sent if a certificate request is received. |
1058 | If a peer does not send a certificate request then the setting | |
a477d280 TB |
1059 | |
1060 | leftsendcert=always | |
1061 | ||
891d332b TB |
1062 | may be used to force sending of the certificate to the other peer. |
1063 | ||
1064 | If a peer certificate contains a _subjectAltName_ extension, then an alternative | |
1065 | `rightid` type can be used, as the example `conn sun` shows. If no `rightid` | |
a477d280 TB |
1066 | entry is present then the subject distinguished name contained in the |
1067 | certificate is taken as the ID. | |
1068 | ||
891d332b | 1069 | Using the same rules concerning pathnames that apply to the gateway's own |
a477d280 TB |
1070 | certificates, the following two definitions are also valid for trusted peer |
1071 | certificates: | |
1072 | ||
1073 | rightcert=peercerts/carolCert.der | |
1074 | ||
1075 | or | |
1076 | ||
1077 | rightcert=/usr/ssl/certs/carolCert.der | |
1078 | ||
1079 | ||
891d332b TB |
1080 | ## Configuring the private keys - ipsec.secrets ## |
1081 | ||
a477d280 | 1082 | |
891d332b | 1083 | ### Loading private key files ### |
a477d280 | 1084 | |
891d332b TB |
1085 | strongSwan is able to load RSA (or ECDSA) private keys in the PKCS#1 or PKCS#8 |
1086 | file formats, or from PKCS#12 containers. The key files can optionally be | |
1087 | secured with a passphrase. | |
a477d280 | 1088 | |
891d332b | 1089 | RSA private key files are declared in `/etc/ipsec.secrets` using the syntax |
a477d280 TB |
1090 | |
1091 | : RSA <my keyfile> "<optional passphrase>" | |
1092 | ||
891d332b | 1093 | The key file can be either in Base64 PEM-format or binary DER-format. The |
a477d280 TB |
1094 | actual coding is detected automatically. The example |
1095 | ||
1096 | : RSA moonKey.pem | |
1097 | ||
1098 | uses a pathname relative to the default directory | |
1099 | ||
1100 | /etc/ipsec.d/private | |
1101 | ||
1102 | As an alternative an absolute pathname can be given as in | |
1103 | ||
1104 | : RSA /usr/ssl/private/moonKey.pem | |
1105 | ||
1106 | In both cases make sure that the key files are root readable only. | |
1107 | ||
1108 | Often a private key must be transported from the Certification Authority | |
1109 | where it was generated to the target security gateway where it is going | |
1110 | to be used. In order to protect the key it can be encrypted with a symmetric | |
1111 | cipher using a transport key derived from a cryptographically strong | |
1112 | passphrase. | |
1113 | ||
1114 | Once on the security gateway the private key can either be permanently | |
891d332b | 1115 | unlocked so that it can be used by the IKE daemon without having to know a |
a477d280 TB |
1116 | passphrase |
1117 | ||
1118 | openssl rsa -in moonKey.pem -out moonKey.pem | |
1119 | ||
1120 | or as an option the key file can remain secured. In this case the passphrase | |
1121 | unlocking the private key must be added after the pathname in | |
891d332b | 1122 | `/etc/ipsec.secrets` |
a477d280 TB |
1123 | |
1124 | : RSA moonKey.pem "This is my passphrase" | |
1125 | ||
891d332b TB |
1126 | Some CAs distribute private keys embedded in a PKCS#12 file. strongSwan can read |
1127 | private keys directly from such a file (end-entity and CA certificates are | |
1128 | also extracted): | |
a477d280 | 1129 | |
891d332b | 1130 | : P12 moonCert.p12 "This is my passphrase" |
a477d280 TB |
1131 | |
1132 | ||
891d332b | 1133 | ### Entering passphrases interactively ### |
a477d280 TB |
1134 | |
1135 | On a VPN gateway you would want to put the passphrase protecting the private | |
891d332b | 1136 | key file right into `/etc/ipsec.secrets` as described in the previous section, |
a477d280 TB |
1137 | so that the gateway can be booted in unattended mode. The risk of keeping |
1138 | unencrypted secrets on a server can be minimized by putting the box into a | |
1139 | locked room. As long as no one can get root access on the machine the private | |
1140 | keys are safe. | |
1141 | ||
1142 | On a mobile laptop computer the situation is quite different. The computer can | |
891d332b | 1143 | be stolen or the user may leave it unattended so that unauthorized persons |
a477d280 | 1144 | can get access to it. In theses cases it would be preferable not to keep any |
891d332b | 1145 | passphrases openly in `/etc/ipsec.secrets` but to prompt for them interactively |
a477d280 TB |
1146 | instead. This is easily done by defining |
1147 | ||
1148 | : RSA moonKey.pem %prompt | |
1149 | ||
1150 | Since strongSwan is usually started during the boot process, usually no | |
1151 | interactive console windows is available which can be used to prompt for | |
1152 | the passphrase. This must be initiated by the user by typing | |
1153 | ||
1154 | ipsec secrets | |
1155 | ||
1156 | which actually is an alias for the existing command | |
1157 | ||
1158 | ipsec rereadsecrets | |
1159 | ||
1160 | and which causes a passphrase prompt to appear. To abort entering a passphrase | |
1161 | enter just a carriage return. | |
1162 | ||
1163 | ||
891d332b | 1164 | ## Configuring CA properties - ipsec.conf ## |
a477d280 | 1165 | |
891d332b | 1166 | Besides the definition of IPsec connections the `ipsec.conf` file can also |
a477d280 TB |
1167 | be used to configure a few properties of the certification authorities |
1168 | needed to establish the X.509 trust chains. The following example shows | |
1169 | some of the parameters that are currently available: | |
1170 | ||
1171 | ca strongswan | |
891d332b TB |
1172 | cacert=strongswanCert.pem |
1173 | ocspuri=http://ocsp.strongswan.org:8880 | |
1174 | crluri=http://crl.strongswan.org/strongswan.crl' | |
1175 | crluri2="ldap://ldap.strongswan.org/O=strongSwan, C=CH?certificateRevocationList" | |
1176 | auto=add | |
a477d280 | 1177 | |
891d332b TB |
1178 | In a similar way as `conn` sections are used for connection definitions, an |
1179 | arbitrary number of optional `ca` sections define the basic properties of CAs. | |
a477d280 TB |
1180 | |
1181 | Each ca section is named with a unique label | |
1182 | ||
891d332b | 1183 | ca strongswan |
a477d280 TB |
1184 | |
1185 | The only mandatory parameter is | |
1186 | ||
891d332b | 1187 | cacert=strongswanCert.pem |
a477d280 TB |
1188 | |
1189 | which points to the CA certificate which usually resides in the default | |
891d332b | 1190 | directory `/etc/ipsec.d/cacerts/` but could also be retrieved via an absolute |
a477d280 TB |
1191 | path name. |
1192 | ||
1193 | The OCSP URI | |
1194 | ||
891d332b | 1195 | ocspuri=http://ocsp.strongswan.org:8880 |
a477d280 TB |
1196 | |
1197 | allows to define an individual OCSP server per CA. Also up to two additional | |
1198 | CRL distribution points (CDPs) can be defined | |
1199 | ||
891d332b TB |
1200 | crluri=http://crl.strongswan.org/strongswan.crl' |
1201 | crluri2="ldap://ldap.strongswan.org/O=strongSwan, C=CH?certificateRevocationList" | |
a477d280 TB |
1202 | |
1203 | which are added to any CDPs already present in the received certificates | |
1204 | themselves. | |
1205 | ||
891d332b TB |
1206 | With the `auto=add` statement the `ca` definition is automatically loaded during |
1207 | startup. Setting `auto=ignore` will ignore the `ca` section. | |
a477d280 TB |
1208 | |
1209 | Any parameters which appear in several ca definitions can be put in | |
891d332b | 1210 | a common `ca %default` section |
a477d280 TB |
1211 | |
1212 | ca %default | |
891d332b | 1213 | crluri=http://crl.strongswan.org/strongswan.crl' |
a477d280 TB |
1214 | |
1215 | ||
891d332b | 1216 | ## Monitoring functions ## |
a477d280 TB |
1217 | |
1218 | strongSwan offers the following monitoring functions: | |
1219 | ||
891d332b TB |
1220 | | Command | Action | |
1221 | |---------------------|---------------------------------------------------| | |
1222 | | ipsec listaacerts | list all Authorization Authority certificates loaded from `/etc/ipsec.d/aacerts/` | | |
1223 | | ipsec listacerts | list all X.509 attribute certificates loaded from `/etc/ipsec.d/acerts/` | | |
1224 | | ipsec listalgs | list cryptographic algorithms for IKE | | |
1225 | | ipsec listcacerts | list all CA certificates loaded from `/etc/ipsec.d/cacerts/` or received via IKE | | |
1226 | | ipsec listcainfos | list all properties defined in `ca` sections in `ipsec.conf` | | |
1227 | | ipsec listcerts | list all certificates loaded via `leftcert` and `rightcert` | | |
1228 | | ipsec listcounters | list global or connection specific counter values | | |
1229 | | ipsec listcrls | list all CLRs loaded from `/etc/ipsec.d/crls/` | | |
1230 | | ipsec listocsp | list contents of the OCSP response cache | | |
1231 | | ipsec listocspcerts | list all OCSP signer certificates loaded from `/etc/ipsec.d/ocspcerts/` or received in OCSP responses | | |
1232 | | ipsec listplugins | list all loaded plugin features | | |
1233 | | ipsec listpubkeys | list all raw public keys e.g. loaded via `leftsigkey` and `rightsigkey` | | |
1234 | | ipsec listall | all the above commands combined | | |
1235 | | ipsec status | list concise status information on established connections | | |
1236 | | ipsec statusall | list detailed status information on connections | | |
a477d280 | 1237 | |
a477d280 | 1238 | |
891d332b | 1239 | ## Firewall support functions ## |
a477d280 | 1240 | |
a477d280 | 1241 | |
891d332b | 1242 | ### Environment variables in the updown script ### |
a477d280 TB |
1243 | |
1244 | strongSwan makes the following environment variables available | |
891d332b TB |
1245 | in the _updown_ script indicated by the `leftupdown` option: |
1246 | ||
1247 | | Variable | Example | Comment | | |
1248 | |-----------------------|---------------------------|-----------------| | |
1249 | | $PLUTO_PEER_ID | carol@strongswan.org | RFC822_ADDR (1) | | |
1250 | | $PLUTO_PEER_PROTOCOL | 17 | udp (2) | | |
1251 | | $PLUTO_PEER_PORT | 68 | bootpc (3) | | |
1252 | | $PLUTO_MY_ID | moon.strongswan.org | FQDN (1) | | |
1253 | | $PLUTO_MY_PROTOCOL | 17 | udp (2) | | |
1254 | | $PLUTO_MY_PORT | 67 | bootps (3) | | |
a477d280 TB |
1255 | |
1256 | (1) $PLUTO_PEER_ID/$PLUTO_MY_ID contain the IDs of the two ends | |
1257 | of an established connection. In our examples these | |
891d332b | 1258 | correspond to the strings defined by `rightid` and `leftid`, |
a477d280 TB |
1259 | respectively. |
1260 | ||
1261 | (2) $PLUTO_PEER_PROTOCOL/$PLUTO_MY_PROTOCOL contain the protocol | |
891d332b | 1262 | defined by the `rightprotoport` and `leftprotoport` options, |
a477d280 TB |
1263 | respectively. Both variables contain the same protocol value. |
1264 | The variables take on the value '0' if no protocol has been defined. | |
1265 | ||
1266 | (3) $PLUTO_PEER_PORT/$PLUTO_MY_PORT contain the ports defined by | |
891d332b | 1267 | the `rightprotoport` and `leftprotoport` options, respectively. |
a477d280 TB |
1268 | The variables take on the value '0' if no port has been defined. |
1269 | ||
a477d280 | 1270 | There are several more, refer to the provided default script for a documentation |
891d332b | 1271 | of them. |
a477d280 TB |
1272 | |
1273 | ||
891d332b | 1274 | ### Automatic insertion and deletion of iptables firewall rules ### |
a477d280 | 1275 | |
891d332b TB |
1276 | The default `_updown` script automatically inserts and deletes dynamic |
1277 | `iptables` firewall rules upon the establishment or teardown, respectively, of | |
1278 | an IPsec security association. This feature is activated with the line | |
a477d280 | 1279 | |
891d332b | 1280 | leftfirewall=yes |
a477d280 | 1281 | |
891d332b TB |
1282 | If you define a `leftsubnet` with a netmask larger than `/32` then the |
1283 | automatically inserted _FORWARD_ `iptables` rules will not allow clients to | |
1284 | access the internal IP address of the gateway even if it is part of that subnet | |
1285 | definition. If you want additional _INPUT_ and _OUTPUT_ `iptables` rules to be | |
1286 | inserted, so that the host itself can be accessed then add the following line: | |
a477d280 | 1287 | |
891d332b | 1288 | lefthostaccess=yes |
a477d280 | 1289 | |
891d332b | 1290 | The `_updown` script also features a logging facility which will register the |
a477d280 TB |
1291 | creation (+) and the expiration (-) of each successfully established VPN |
1292 | connection in a special syslog file in the following concise and easily | |
1293 | readable format: | |
1294 | ||
891d332b TB |
1295 | Jul 19 18:58:38 moon vpn: |
1296 | + carol.strongswan.org 192.168.0.100 -- 192.168.0.1 == 10.1.0.0/16 | |
1297 | Jul 19 22:15:17 moon vpn: | |
1298 | - carol.strongswan.org 192.168.0.100 -- 192.168.0.1 == 10.1.0.0/16 |