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