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