]>
Commit | Line | Data |
---|---|---|
1 | # strongSwan Configuration # | |
2 | ||
3 | ## Overview ## | |
4 | ||
5 | strongSwan is an OpenSource IPsec-based VPN solution. | |
6 | ||
7 | This document is just a short introduction, for more detailed information | |
8 | consult the man pages and [**our wiki**](http://wiki.strongswan.org). | |
9 | ||
10 | ||
11 | ## Quickstart ## | |
12 | ||
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. | |
15 | ||
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. | |
21 | ||
22 | ||
23 | ### Site-to-site case ### | |
24 | ||
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 | |
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 | ||
32 | Configuration on gateway _moon_: | |
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 | ||
52 | Configuration on gateway _sun_: | |
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 | ||
73 | ### Host-to-host case ### | |
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 | ||
82 | Configuration on host _moon_: | |
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 | ||
100 | Configuration on host _sun_: | |
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 | ||
119 | ### Roadwarrior case ### | |
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 | ||
127 | Configuration on gateway _moon_: | |
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 | ||
145 | Configuration on roadwarrior _carol_: | |
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 | ||
165 | ### Roadwarrior case with virtual IP ### | |
166 | ||
167 | Roadwarriors usually have dynamic IP addresses assigned by the ISP they are | |
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. | |
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 | |
176 | `10.3.0.0/16` which can be configured by adding the parameter | |
177 | ||
178 | rightsourceip=10.3.0.0/16 | |
179 | ||
180 | to the gateway's `ipsec.conf`. To request an IP address from this pool a | |
181 | roadwarrior can use IKEv1 mode config or IKEv2 configuration payloads. | |
182 | The configuration for both is the same | |
183 | ||
184 | leftsourceip=%config | |
185 | ||
186 | Configuration on gateway _moon_: | |
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 | ||
205 | Configuration on roadwarrior _carol_: | |
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 | ||
226 | ## Generating certificates and CRLs ## | |
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 | ||
233 | ### Generating a CA certificate ### | |
234 | ||
235 | The OpenSSL statement | |
236 | ||
237 | openssl req -x509 -days 1460 -newkey rsa:4096 \ | |
238 | -keyout strongswanKey.pem -out strongswanCert.pem | |
239 | ||
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). | |
242 | ||
243 | openssl x509 -in cert.pem -noout -text | |
244 | ||
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. | |
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 | |
263 | stores keys and certificates in the binary DER format by default. | |
264 | The `--outform` option may be used to write PEM encoded files. | |
265 | ||
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. | |
269 | ||
270 | ||
271 | ### Generating a host or user certificate ### | |
272 | ||
273 | The OpenSSL statement | |
274 | ||
275 | openssl req -newkey rsa:2048 -keyout hostKey.pem \ | |
276 | -out hostReq.pem | |
277 | ||
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. | |
280 | ||
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: | |
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 | ||
291 | if you want the ID to be of type _IPV4_ADDR_. Of course you could include both | |
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 | ||
299 | For user certificates the appropriate ID type is _RFC822_ADDR_ which can be | |
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 | ||
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. | |
316 | ||
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: | |
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 | ||
345 | do something similar using the strongSwan PKI tool. | |
346 | ||
347 | Usually, a Windows or Mac OS X (or iOS) based VPN client needs its private key, | |
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: | |
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 | ||
357 | ### Generating a CRL ### | |
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 | ||
363 | If you omit the `-crldays` option then the `default_crl_days` value (30 days) | |
364 | specified in `openssl.cnf` is used. | |
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 | ||
371 | The strongSwan PKI tool provides the `--signcrl` command to sign CRLs. | |
372 | ||
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 | |
375 | will be determined. | |
376 | ||
377 | ||
378 | ### Revoking a certificate ### | |
379 | ||
380 | A specific host certificate stored in the file `host.pem` is revoked with the | |
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 | ||
393 | in the case of a Base64 CRL, or alternatively for a CRL in DER format | |
394 | ||
395 | openssl crl -inform DER -in cert.crl -noout -text | |
396 | ||
397 | Again the `--signcrl` command of the strongSwan PKI tool may also be used to | |
398 | create new CRLs containing additional certificates. | |
399 | ||
400 | ||
401 | ## Configuring the connections - ipsec.conf ## | |
402 | ||
403 | ### Configuring my side ### | |
404 | ||
405 | Usually the **local** side is the same for all connections. Therefore it makes | |
406 | sense to put the definitions characterizing the strongSwan security gateway into | |
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 | |
410 | ||
411 | conn %default | |
412 | leftcert=moonCert.pem | |
413 | # load connection definitions automatically | |
414 | auto=add | |
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 | ||
422 | The certificate can either be stored in Base64 PEM-format or in the binary | |
423 | DER-format. Irrespective of the file suffix the correct format will be | |
424 | determined. Therefore `leftcert=moonCert.der` or `leftcert=moonCert.cer` | |
425 | would also be valid alternatives. | |
426 | ||
427 | When using relative pathnames as in the examples above, the certificate files | |
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 | |
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 | ||
442 | conn rw | |
443 | right=%any | |
444 | leftid=moon.strongswan.org | |
445 | ||
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. | |
450 | ||
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_ | |
453 | and which can be written e.g. in the LDAP-type format | |
454 | ||
455 | conn rw | |
456 | right=%any | |
457 | leftid="C=CH, O=strongSwan, CN=moon.strongswan.org" | |
458 | ||
459 | Since the subject's DN is part of the certificate, the `leftid` does not have to | |
460 | be declared explicitly. Thus the entry | |
461 | ||
462 | conn rw | |
463 | right=%any | |
464 | ||
465 | automatically assumes the subject DN of `leftcert` to be the host ID. | |
466 | ||
467 | ||
468 | ### Multiple certificates ### | |
469 | ||
470 | strongSwan supports multiple local host certificates and corresponding | |
471 | RSA private keys: | |
472 | ||
473 | conn rw1 | |
474 | right=%any | |
475 | rightid=peer1.domain1 | |
476 | leftcert=myCert1.pem | |
477 | # leftid is DN of myCert1 | |
478 | ||
479 | conn rw2 | |
480 | right=%any | |
481 | rightid=peer2.domain2 | |
482 | leftcert=myCert2.pem | |
483 | # leftid is DN of myCert2 | |
484 | ||
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_. | |
488 | ||
489 | ||
490 | ### Configuring the peer side using CA certificates ### | |
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 | ||
496 | conn rw | |
497 | right=%any | |
498 | ||
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. | |
505 | ||
506 | The ID by which a peer is identifying itself during IKE can by any of the ID | |
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 | |
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 | |
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. | |
520 | ||
521 | The Relative Distinguished Names (RDNs) can alternatively be separated by a | |
522 | slash `/` instead of a comma `,` | |
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 | |
527 | `-subject` command line option | |
528 | ||
529 | openssl x509 -in sunCert.pem -noout -subject | |
530 | ||
531 | The following RDNs are supported by strongSwan | |
532 | ||
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 | | |
564 | ||
565 | With the roadwarrior connection definition listed above, an IPsec SA for | |
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 | |
569 | definitions will make this possible | |
570 | ||
571 | conn rw1 | |
572 | right=%any | |
573 | leftsubnet=10.1.0.0/24 | |
574 | ||
575 | conn rw3 | |
576 | right=%any | |
577 | leftsubnet=10.1.3.0/24 | |
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 | |
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`: | |
589 | ||
590 | conn sun | |
591 | right=%any | |
592 | rightid=sun.strongswan.org | |
593 | ||
594 | conn carol | |
595 | right=%any | |
596 | rightid=carol@strongswan.org | |
597 | ||
598 | conn dave | |
599 | right=%any | |
600 | rightid="C=CH, O=strongSwan, CN=dave@strongswan.org" | |
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 | ||
606 | conn sun | |
607 | right=192.168.0.2 | |
608 | rightid=sun.strongswan.org | |
609 | ||
610 | conn carol | |
611 | right=192.168.0.100 | |
612 | rightid=carol@strongswan.org | |
613 | ||
614 | conn dave | |
615 | right=192.168.0.200 | |
616 | rightid="C=CH, O=strongSwan, CN=dave@strongswan.org" | |
617 | ||
618 | conn venus | |
619 | right=192.168.0.50 | |
620 | ||
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. | |
625 | ||
626 | ||
627 | ### Handling Virtual IPs and narrowing ### | |
628 | ||
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`: | |
636 | ||
637 | conn rw1 | |
638 | right=%any | |
639 | righsubnet=10.4.0.5/32 | |
640 | ||
641 | conn rw2 | |
642 | right=%any | |
643 | rightsubnet=10.4.0.47/32 | |
644 | ||
645 | conn rw3 | |
646 | right=%any | |
647 | rightsubnet=10.4.0.128/28 | |
648 | ||
649 | Because the charon daemon uses narrowing (even for IKEv1) these three entries | |
650 | can be reduced to the single connection definition | |
651 | ||
652 | conn rw | |
653 | right=%any | |
654 | rightsubnet=10.4.0.0/24 | |
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 | |
658 | within the boundaries defined by the subnet definition (in our example | |
659 | `10.4.0.0/24`). | |
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 | ||
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 | |
668 | ||
669 | conn rw | |
670 | right=%any | |
671 | rightsourceip=10.5.0.0/24 | |
672 | ||
673 | ||
674 | ### Protocol and Port Selectors ### | |
675 | ||
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`. | |
680 | ||
681 | Some examples: | |
682 | ||
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 | |
708 | ||
709 | Protocols and ports can be designated either by their numerical values | |
710 | or by their acronyms defined in `/etc/services`. | |
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 | ||
717 | ### IPsec policies based on wildcards ### | |
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 | |
723 | distinguished name (_ID_DER_ASN1_DN_). | |
724 | ||
725 | Let's make a practical example: | |
726 | ||
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 | |
731 | assigned statically or from a dynamic pool. The sales and research departments | |
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_). | |
737 | ||
738 | The IPsec policy defined above can now be enforced with the following three | |
739 | IPsec security associations: | |
740 | ||
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. | |
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=*" | |
771 | "C=CH, O=ACME, OU=*, OU=Special Effects, CN=*" | |
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 | ||
781 | ### IPsec policies based on CA certificates ### | |
782 | ||
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 | |
786 | ||
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 | |
792 | ||
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 | |
798 | ||
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 | |
806 | ||
807 | In the example above, the connection _sales_ can be used by peers | |
808 | presenting certificates issued by the Sales CA, only. In the same way, | |
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 | |
813 | then any valid certificate issued by one of the trusted CAs in | |
814 | `/etc/ipsec.d/cacerts` can be used by the peer. | |
815 | ||
816 | The `leftca` parameter usually doesn't have to be set explicitly because | |
817 | by default it is set to the issuer field of the certificate loaded via | |
818 | `leftcert`. The statement | |
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 | ||
825 | conn sales | |
826 | right=%any | |
827 | rightca=%same | |
828 | leftcert=mySalesCert.pem | |
829 | ||
830 | ||
831 | ## Configuring certificates and CRLs ## | |
832 | ||
833 | ||
834 | ### Installing the CA certificates ### | |
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 | |
841 | must be copied in either binary DER or Base64 PEM format into the directory | |
842 | ||
843 | /etc/ipsec.d/cacerts/ | |
844 | ||
845 | ||
846 | ### Installing optional certificate revocation lists (CRLs) ### | |
847 | ||
848 | By copying a CA certificate into `/etc/ipsec.d/cacerts/`, automatically all user | |
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 | |
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 | |
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 | |
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_ | |
864 | field of the CRL has been reached, a warning is issued but the public key will | |
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. | |
867 | ||
868 | ||
869 | ### Dynamic update of certificates and CRLs ### | |
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 | |
876 | indicated by the _nextUpdate_ field in the CRL body. The following interactive | |
877 | commands allow the manual replacement of the various files: | |
878 | ||
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 | ||
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 | ||
898 | ### Local caching of CRLs ### | |
899 | ||
900 | The `ipsec.conf` option | |
901 | ||
902 | config setup | |
903 | cachecrls=yes | |
904 | ||
905 | activates the local caching of CRLs that were dynamically fetched from an | |
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`. | |
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 | ||
915 | ### Online Certificate Status Protocol (OCSP) ### | |
916 | ||
917 | The _Online Certificate Status Protocol_ is defined by RFC 2560. It can be | |
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 | |
922 | TCP/HTTP connection. | |
923 | ||
924 | In the simplest OCSP setup, a default URI under which the OCSP server for a | |
925 | given CA can be accessed is defined in `ipsec.conf`: | |
926 | ||
927 | ca strongswan | |
928 | cacert=strongswanCert.pem | |
929 | ocspuri=http://ocsp.strongswan.org:8880 | |
930 | auto=add | |
931 | ||
932 | The HTTP port can be freely chosen. | |
933 | ||
934 | OpenSSL implements an OCSP server that can be used in conjunction with an | |
935 | OpenSSL-based Public Key Infrastructure. The OCSP server is started with the | |
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 | ||
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. | |
950 | ||
951 | -CA the CA certificate | |
952 | ||
953 | -port the HTTP port the OCSP server is listening on. | |
954 | ||
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. | |
960 | ||
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. | |
965 | ||
966 | -resp_no_certs With this option the OCSP signer certificate defined by | |
967 | -rsigner is not included in the OCSP response. | |
968 | ||
969 | -nmin the validity interval of an OCSP response given in minutes. | |
970 | ||
971 | -text this option activates a verbose logging output, showing the | |
972 | contents of both the received OCSP request and sent OCSP response. | |
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 | ||
986 | in the `[ usr_cert ]` section of your `openssl.cnf` configuration file before | |
987 | the CA signs the OCSP server certificate. | |
988 | ||
989 | For a given CA the corresponding _ca_ section in `ipsec.conf` (see below) allows | |
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 | ||
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 | |
997 | record overrides the default URI defined by the ca section. | |
998 | ||
999 | ||
1000 | ### CRL Policy ### | |
1001 | ||
1002 | By default strongSwan is quite tolerant concerning the handling of CRLs. It is | |
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. | |
1007 | ||
1008 | If you want to enforce a stricter CRL policy then you can do this by setting | |
1009 | the `strictcrlpolicy` option. This is done in the `config setup` section | |
1010 | of the `ipsec.conf` file: | |
1011 | ||
1012 | config setup | |
1013 | strictcrlpolicy=yes | |
1014 | ... | |
1015 | ||
1016 | A certificate received from a peer will not be accepted if no corresponding | |
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 | |
1020 | the connection in question to fail. Therefore if you are going to use the | |
1021 | `strictcrlpolicy=yes` option, make sure that the CRLs will always be updated | |
1022 | in time. Otherwise a total standstill might ensue. | |
1023 | ||
1024 | As mentioned earlier the default setting is `strictcrlpolicy=no`. | |
1025 | ||
1026 | ||
1027 | ### Configuring the peer side using locally stored certificates ### | |
1028 | ||
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. | |
1031 | ||
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 | |
1035 | ||
1036 | conn sun | |
1037 | right=%any | |
1038 | rightid=sun.strongswan.org | |
1039 | rightcert=sunCert.cer | |
1040 | ||
1041 | conn carol | |
1042 | right=192.168.0.100 | |
1043 | rightcert=carolCert.der | |
1044 | ||
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 | |
1049 | ||
1050 | leftsendcert=never | |
1051 | ||
1052 | to the connection definition(s) in order to avoid the sending of the host's | |
1053 | own certificate. The default value is | |
1054 | ||
1055 | leftsendcert=ifasked | |
1056 | ||
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 | |
1059 | ||
1060 | leftsendcert=always | |
1061 | ||
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` | |
1066 | entry is present then the subject distinguished name contained in the | |
1067 | certificate is taken as the ID. | |
1068 | ||
1069 | Using the same rules concerning pathnames that apply to the gateway's own | |
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 | ||
1080 | ## Configuring the private keys - ipsec.secrets ## | |
1081 | ||
1082 | ||
1083 | ### Loading private key files ### | |
1084 | ||
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. | |
1088 | ||
1089 | RSA private key files are declared in `/etc/ipsec.secrets` using the syntax | |
1090 | ||
1091 | : RSA <my keyfile> "<optional passphrase>" | |
1092 | ||
1093 | The key file can be either in Base64 PEM-format or binary DER-format. The | |
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 | |
1115 | unlocked so that it can be used by the IKE daemon without having to know a | |
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 | |
1122 | `/etc/ipsec.secrets` | |
1123 | ||
1124 | : RSA moonKey.pem "This is my passphrase" | |
1125 | ||
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): | |
1129 | ||
1130 | : P12 moonCert.p12 "This is my passphrase" | |
1131 | ||
1132 | ||
1133 | ### Entering passphrases interactively ### | |
1134 | ||
1135 | On a VPN gateway you would want to put the passphrase protecting the private | |
1136 | key file right into `/etc/ipsec.secrets` as described in the previous section, | |
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 | |
1143 | be stolen or the user may leave it unattended so that unauthorized persons | |
1144 | can get access to it. In theses cases it would be preferable not to keep any | |
1145 | passphrases openly in `/etc/ipsec.secrets` but to prompt for them interactively | |
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 | ||
1164 | ## Configuring CA properties - ipsec.conf ## | |
1165 | ||
1166 | Besides the definition of IPsec connections the `ipsec.conf` file can also | |
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 | |
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 | |
1177 | ||
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. | |
1180 | ||
1181 | Each ca section is named with a unique label | |
1182 | ||
1183 | ca strongswan | |
1184 | ||
1185 | The only mandatory parameter is | |
1186 | ||
1187 | cacert=strongswanCert.pem | |
1188 | ||
1189 | which points to the CA certificate which usually resides in the default | |
1190 | directory `/etc/ipsec.d/cacerts/` but could also be retrieved via an absolute | |
1191 | path name. | |
1192 | ||
1193 | The OCSP URI | |
1194 | ||
1195 | ocspuri=http://ocsp.strongswan.org:8880 | |
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 | ||
1200 | crluri=http://crl.strongswan.org/strongswan.crl' | |
1201 | crluri2="ldap://ldap.strongswan.org/O=strongSwan, C=CH?certificateRevocationList" | |
1202 | ||
1203 | which are added to any CDPs already present in the received certificates | |
1204 | themselves. | |
1205 | ||
1206 | With the `auto=add` statement the `ca` definition is automatically loaded during | |
1207 | startup. Setting `auto=ignore` will ignore the `ca` section. | |
1208 | ||
1209 | Any parameters which appear in several ca definitions can be put in | |
1210 | a common `ca %default` section | |
1211 | ||
1212 | ca %default | |
1213 | crluri=http://crl.strongswan.org/strongswan.crl' | |
1214 | ||
1215 | ||
1216 | ## Monitoring functions ## | |
1217 | ||
1218 | strongSwan offers the following monitoring functions: | |
1219 | ||
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 | | |
1237 | ||
1238 | ||
1239 | ## Firewall support functions ## | |
1240 | ||
1241 | ||
1242 | ### Environment variables in the updown script ### | |
1243 | ||
1244 | strongSwan makes the following environment variables available | |
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) | | |
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 | |
1258 | correspond to the strings defined by `rightid` and `leftid`, | |
1259 | respectively. | |
1260 | ||
1261 | (2) $PLUTO_PEER_PROTOCOL/$PLUTO_MY_PROTOCOL contain the protocol | |
1262 | defined by the `rightprotoport` and `leftprotoport` options, | |
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 | |
1267 | the `rightprotoport` and `leftprotoport` options, respectively. | |
1268 | The variables take on the value '0' if no port has been defined. | |
1269 | ||
1270 | There are several more, refer to the provided default script for a documentation | |
1271 | of them. | |
1272 | ||
1273 | ||
1274 | ### Automatic insertion and deletion of iptables firewall rules ### | |
1275 | ||
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 | |
1279 | ||
1280 | leftfirewall=yes | |
1281 | ||
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: | |
1287 | ||
1288 | lefthostaccess=yes | |
1289 | ||
1290 | The `_updown` script also features a logging facility which will register the | |
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 | ||
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 |