]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
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 Four Tunnel case | |
14 | 2.4 Four Tunnel case the elegant way with source routing | |
15 | 2.5 Roadwarrior case | |
16 | 2.6 Roadwarrior case with virtual IP | |
17 | 3. Generating X.509 certificates and CRLs with OpenSSL | |
18 | 3.1 Generating a CA certificate | |
19 | 3.2 Generating a host or user certificate | |
20 | 3.3 Generating a CRL | |
21 | 3.4 Revoking a certificate | |
22 | 4. Configuring the connections - ipsec.conf | |
23 | 4.1 Configuring my side | |
24 | 4.2 Multiple certificates | |
25 | 4.3 Configuring the peer side using CA certificates | |
26 | 4.4 Handling Virtual IPs and wildcard subnets | |
27 | 4.5 Protocol and port selectors | |
28 | 4.6 IPsec policies based on wildcards | |
29 | 4.7 IPsec policies based on CA certificates | |
30 | 4.8 Sending certificate requests | |
31 | 4.9 IPsec policies based on group attributes | |
32 | 5. Configuring certificates and CRLs | |
33 | 5.1 Installing CA certificates | |
34 | 5.2 Installing optional Certificate Revocation Lists (CRLs) | |
35 | 5.3 Dynamic update of certificates and CRLs | |
36 | 5.4 Local caching of CRLs | |
37 | 5.5 Online Certificate Status Protocol (OCSP) | |
38 | 5.6 CRL policy | |
39 | 5.7 Configuring the peer side using locally stored certificates | |
40 | 6. Configuring the private keys - ipsec.secrets | |
41 | 6.1 Loading private key files in PKCS#1 format | |
42 | 6.2 Entering passphrases interactively | |
43 | 6.3 Multiple private keys | |
846e4b05 | 44 | 7. Configuring CA properties - ipsec.conf |
997358a6 MW |
45 | 8. Smartcard support |
46 | 8.1 Configuring a smartcard-based connection | |
47 | 8.2 Entering the PIN code | |
48 | 8.3 PIN-pad equipped smartcard readers | |
49 | 8.4 Configuring a smartcard using pkcs15-init | |
50 | 8.5 PKCS#1 proxy functions | |
51 | 9. Configuring the clients | |
52 | 9.1 strongSwan | |
53 | 9.2 PGPnet | |
54 | 9.3 Safenet/Soft-Remote | |
55 | 9.4 SSH Sentinel | |
56 | 9.5 Windows 2000/XP | |
57 | 10. Monitoring functions | |
58 | 11. Firewall support functions | |
59 | 11.1 Environment variables in the updown script | |
280f5aeb | 60 | 11.2 Automatic insertion and deletion of iptables firewall rules |
997358a6 MW |
61 | 11.3 Sample Linux 2.6 _updown_espmark script for iptables < 1.3.5 |
62 | 12. Authentication with raw RSA public keys | |
63 | 13. Authentication with OpenPGP certificates | |
64 | 13.1 OpenPGP certificates | |
65 | 13.2 OpenPGP private keys | |
66 | 13.3 Monitoring functions | |
67 | 13.4 Suppression of certificate request messages | |
68 | 14. Additional features | |
69 | 14.1 Authentication and encryption algorithms | |
70 | 14.2 NAT traversal | |
71 | 14.3 Dead peer detection | |
280f5aeb AS |
72 | 14.4 IKE Mode Config Pull Mode |
73 | 14.5 IKE Mode Config Push Mode | |
74 | 14.6 XAUTH - Extended Authentication (NEW) | |
997358a6 MW |
75 | 15. Copyright statement and acknowledgements |
76 | ||
77 | ||
78 | 1. Overview | |
79 | -------- | |
80 | ||
81 | strongSwan is an OpenSource IPsec solution for the Linux operating system | |
82 | and currently supports the following features: | |
83 | ||
84 | * runs both on Linux 2.4 (KLIPS) and Linux 2.6 (native IPsec) kernels. | |
85 | ||
86 | * strong 3DES, AES, Serpent, Twofish, or Blowfish encryption. | |
87 | ||
88 | * Authentication based on X.509 certificates or preshared secrets. | |
89 | ||
90 | * IPsec policies based on wildcards or intermediate CAs. | |
91 | ||
92 | * Powerful and flexible IPsec policies based on group attributes. | |
93 | ||
94 | * Retrieval of Certificate Revocation Lists (CRLs) via HTTP or LDAP. | |
95 | ||
96 | * Local caching of fetched CRLs | |
97 | ||
98 | * Full support of the Online Certificate Status Protocol (OCSP, RFC 2560). | |
99 | ||
100 | * CA management functions including OCSP and CRL URIs and default LDAP server. | |
101 | ||
102 | * Optional storage of RSA private keys on smartcards or USB crypto tokens | |
103 | ||
104 | * Standardized PKCS#11 interface with optional proxy functions serving | |
105 | external applications (disc encryption, etc.). | |
106 | ||
107 | * NAT-Traversal (RFC 3947) | |
108 | ||
280f5aeb AS |
109 | * Support of Virtual IPs via static configuration and IKE Mode Config |
110 | ||
111 | * XAUTH client and server functionality in conjunction with either PSK | |
112 | or RSA IKE Main Mode authentication. | |
997358a6 MW |
113 | |
114 | * Support of Delete SA and informational Notification messages. | |
115 | ||
116 | * Dead Peer Detection (DPD, RFC 3706) | |
117 | ||
118 | Compatibility has successfully been tested with peers running the following | |
119 | IPsec clients: | |
120 | ||
121 | FreeS/WAN, Openswan, SafeNet/SoftRemote, NCP Secure Entry Client, | |
122 | SonicWALL Global VPN Client, The GreenBow, Microsoft Windows 2000/XP, etc. | |
123 | ||
124 | Furthermore, interoperability with the following VPN gateways | |
125 | has been demonstrated during the IPsec 2001 Conference in Paris: | |
126 | ||
127 | Cisco IOS Routers, Cisco PIX firewall, Cisco VPN3000, | |
128 | Nortel Contivity VPN Switch, NetScreen (FreeS/WAN as responder only), | |
129 | OpenBSD with isakmpd, Netasq, Netcelo, and 6WIND. | |
130 | ||
131 | Potentially any IPsec implementation with X.509 certificate support can | |
132 | be made to cooperate with strongSwan. The latest addition has been the successful | |
133 | interoperability with the Check Point VPN-1 NG gateway. | |
134 | ||
135 | ||
136 | 2. Quickstart | |
137 | ---------- | |
138 | ||
139 | In the following examples we assume for reasons of clarity that left designates | |
140 | the local host and that right is the remote host. Certificates for users, hosts | |
141 | and gateways are issued by a ficticious strongSwan CA. How to generate private keys | |
142 | and certificates using OpenSSL will be explained in section 3. The CA certificate | |
143 | "strongswanCert.pem" must be present on all VPN end points in order to be able to | |
144 | authenticate the peers. | |
145 | ||
146 | ||
147 | 2.1 Site-to-site case | |
148 | ----------------- | |
149 | ||
150 | In this scenario two security gateways moon and sun will connect the | |
151 | two subnets moon-net and sun-net with each other through a VPN tunnel | |
152 | set up between the two gateways: | |
153 | ||
154 | 10.1.0.0/16 -- | 192.168.0.1 | === | 192.168.0.2 | -- 10.2.0.0/16 | |
155 | moon-net moon sun sun-net | |
156 | ||
157 | Configuration on gateway moon: | |
158 | ||
159 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
160 | ||
161 | /etc/ipsec.d/certs/moonCert.pem | |
162 | ||
163 | /etc/ipsec.secrets: | |
164 | ||
165 | : RSA moonKey.pem "<optional passphrase>" | |
166 | ||
167 | /etc/ipsec.conf: | |
168 | ||
169 | conn net-net | |
170 | left=%defaultroute | |
171 | leftsubnet=10.1.0.0/16 | |
172 | leftcert=moonCert.pem | |
173 | right=192.168.0.2 | |
174 | rightsubnet=10.2.0.0/16 | |
175 | rightid="C=CH, O=Linux strongSwan, CN=sun.strongswan.org" | |
176 | auto=start | |
177 | ||
178 | Configuration on gateway sun: | |
179 | ||
180 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
181 | ||
182 | /etc/ipsec.d/certs/sunCert.pem | |
183 | ||
184 | /etc/ipsec.secrets: | |
185 | ||
186 | : RSA sunKey.pem "<optional passphrase>" | |
187 | ||
188 | /etc/ipsec.conf: | |
189 | ||
190 | conn net-net | |
191 | left=%defaultroute | |
192 | leftsubnet=10.2.0.0/16 | |
193 | leftcert=sunCert.pem | |
194 | right=192.168.0.1 | |
195 | rightsubnet=10.1.0.0/16 | |
196 | rightid="C=CH, O=Linux strongSwan, CN=moon.strongswan.org" | |
197 | auto=start | |
198 | ||
199 | ||
200 | 2.2 Host-to-host case | |
201 | ----------------- | |
202 | ||
203 | This is a setup between two single hosts which don't have a subnet behind | |
204 | them. Although IPsec transport mode would be sufficient for host-to-host | |
205 | connections we will use the default IPsec tunnel mode. | |
206 | ||
207 | | 192.168.0.1 | === | 192.168.0.2 | | |
208 | moon sun | |
209 | ||
210 | Configuration on host moon: | |
211 | ||
212 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
213 | ||
214 | /etc/ipsec.d/certs/moonCert.pem | |
215 | ||
216 | /etc/ipsec.secrets: | |
217 | ||
218 | : RSA moonKey.pem "<optional passphrase>" | |
219 | ||
220 | /etc/ipsec.conf: | |
221 | ||
222 | conn host-host | |
223 | left=%defaultroute | |
224 | leftcert=moonCert.pem | |
225 | right=192.168.0.2 | |
226 | rightid="C=CH, O=Linux strongSwan, CN=sun.strongswan.org" | |
227 | auto=start | |
228 | ||
229 | Configuration on host sun: | |
230 | ||
231 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
232 | ||
233 | /etc/ipsec.d/certs/sunCert.pem | |
234 | ||
235 | /etc/ipsec.secrets: | |
236 | ||
237 | : RSA sunKey.pem "<optional passphrase>" | |
238 | ||
239 | /etc/ipsec.conf: | |
240 | ||
241 | conn host-host | |
242 | left=%defaultroute | |
243 | leftcert=sunCert.pem | |
244 | right=192.168.0.1 | |
245 | rightid="C=CH, O=Linux strongSwan, CN=moon.strongswan.org" | |
246 | auto=start | |
247 | ||
248 | ||
249 | 2.3 Four Tunnel case | |
250 | ---------------- | |
251 | ||
252 | In a site-to-site setup a system administrator logged into the local gateway | |
253 | often would like to access the peer gateway or a server in the subnet behind | |
254 | the peer gateway over a secure IPsec tunnel.Since IP packets leaving a gateway | |
255 | via the outer network interface carry the IP address of this NIC, four IPsec | |
256 | Security Associations (SAs) must be set up to achieve full connectivity. The | |
257 | example below shows how this can be done without much additional typing work , | |
258 | using the "also" macro which includes connection definitions defined farther | |
259 | down in the ipsec.conf file. | |
260 | ||
261 | 10.1.0.0/16 -- | 192.168.0.1 | === | 192.168.0.2 | -- 10.2.0.0/16 | |
262 | moon-net moon sun sun-net | |
263 | ||
264 | Configuration on gateway moon: | |
265 | ||
266 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
267 | ||
268 | /etc/ipsec.d/certs/moonCert.pem | |
269 | ||
270 | /etc/ipsec.secrets: | |
271 | ||
272 | : RSA moonKey.pem "<optional passphrase>" | |
273 | ||
274 | /etc/ipsec.conf: | |
275 | ||
276 | conn net-net | |
277 | leftsubnet=10.1.0.0/16 | |
278 | rightsubnet=10.2.0.0/16 | |
279 | also host-host | |
280 | ||
281 | conn net-host | |
282 | leftsubnet=10.1.0.0/16 | |
283 | also host-host | |
284 | ||
285 | conn host-net | |
286 | rightsubnet=10.2.0.0/16 | |
287 | also host-host | |
288 | ||
289 | conn host-host | |
290 | left=%defaultroute | |
291 | leftcert=moonCert.pem | |
292 | right=192.168.0.2 | |
293 | rightid="C=CH, O=Linux strongSwan, CN=sun.strongswan.org" | |
294 | auto=start | |
295 | ||
296 | Configuration on gateway sun: | |
297 | ||
298 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
299 | ||
300 | /etc/ipsec.d/certs/sunCert.pem | |
301 | ||
302 | /etc/ipsec.secrets: | |
303 | ||
304 | : RSA sunKey.pem "<optional passphrase>" | |
305 | ||
306 | /etc/ipsec.conf: | |
307 | ||
308 | conn net-net | |
309 | leftsubnet=10.2.0.0/16 | |
310 | rightsubnet=10.1.0.0/16 | |
311 | also=host-host | |
312 | ||
313 | conn net-host | |
314 | leftsubnet=10.2.0.0/16 | |
315 | also=host-host | |
316 | ||
317 | conn host-net | |
318 | rightsubnet=10.1.0.0/16 | |
319 | also=host-host | |
320 | ||
321 | conn host-host | |
322 | left=%defaultroute | |
323 | leftcert=sunCert.pem | |
324 | right=192.168.0.1 | |
325 | rightid="C=CH, O=Linux strongSwan, CN=moon.strongswan.org" | |
326 | auto=start | |
327 | ||
328 | ||
329 | 2.4 The four tunnel case the elegant way with source routing | |
330 | -------------------------------------------------------- | |
331 | ||
332 | As you certainly agree, the full four tunnel case described in the previous | |
333 | section becomes quite complex. If we could force the source address of the | |
334 | IP packets leaving the gateway through the outer interface to take on the | |
335 | IP address of the inner interface then we could use the single subnet-to-subnet | |
336 | tunnel from section 2.1. Such a setup becomes possible if we use the | |
337 | source routing capabilites of the ip route command that is already used | |
338 | by strongSwan's updown scripts. | |
339 | ||
340 | 10.1.0.0/16 -- | 192.168.0.1 | === | 192.168.0.2 | -- 10.2.0.0/16 | |
341 | moon-net moon sun sun-net | |
342 | ||
343 | If we assume that the inner IP address of gateway moon is 10.1.0.1 | |
344 | and the inner IP address of gateway sun is 10.2.0.1 then the | |
345 | insertion of the parameter | |
346 | ||
347 | leftsourceip=10.1.0.1 | |
348 | ||
349 | in the connection definition of moon and | |
350 | ||
351 | leftsourceip=10.2.0.1 | |
352 | ||
353 | on sun, respectively, will install source routing on both gateways. | |
354 | As a result the command | |
355 | ||
356 | ping 10.2.0.1 | |
357 | ||
358 | executed on moon will leave the gateway with a source address of | |
359 | 10.1.0.1 and will therefore take the net-net IPsec tunnel. | |
360 | ||
361 | Configuration on gateway moon: | |
362 | ||
363 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
364 | ||
365 | /etc/ipsec.d/certs/moonCert.pem | |
366 | ||
367 | /etc/ipsec.secrets: | |
368 | ||
369 | : RSA moonKey.pem "<optional passphrase>" | |
370 | ||
371 | /etc/ipsec.conf: | |
372 | ||
373 | conn net-net | |
374 | left=%defaultroute | |
375 | leftsourceip=10.1.0.1 | |
376 | leftsubnet=10.1.0.0/16 | |
377 | leftcert=moonCert.pem | |
378 | right=192.168.0.2 | |
379 | rightsubnet=10.2.0.0/16 | |
380 | rightid="C=CH, O=Linux strongSwan, CN=sun.strongswan.org" | |
381 | auto=start | |
382 | ||
383 | Configuration on gateway sun: | |
384 | ||
385 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
386 | ||
387 | /etc/ipsec.d/certs/sunCert.pem | |
388 | ||
389 | /etc/ipsec.secrets: | |
390 | ||
391 | : RSA sunKey.pem "<optional passphrase>" | |
392 | ||
393 | /etc/ipsec.conf: | |
394 | ||
395 | conn net-net | |
396 | left=%defaultroute | |
397 | leftsubnet=10.2.0.0/16 | |
398 | leftsourceip=10.2.0.1 | |
399 | leftcert=sunCert.pem | |
400 | right=192.168.0.1 | |
401 | rightsubnet=10.1.0.0/16 | |
402 | rightid="C=CH, O=Linux strongSwan, CN=moon.strongswan.org" | |
403 | auto=start | |
404 | ||
405 | ||
406 | 2.5 Roadwarrior case | |
407 | ---------------- | |
408 | ||
409 | This is a very common case where a strongSwan gateway serves an arbitrary number | |
410 | of remote VPN clients usually having dynamic IP addresses. | |
411 | ||
412 | 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x | | |
413 | moon-net moon carol | |
414 | ||
415 | Configuration on gateway moon: | |
416 | ||
417 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
418 | ||
419 | /etc/ipsec.d/certs/moonCert.pem | |
420 | ||
421 | /etc/ipsec.secrets: | |
422 | ||
423 | : RSA moonKey.pem "<optional passphrase>" | |
424 | ||
425 | /etc/ipsec.conf: | |
426 | ||
427 | conn rw | |
428 | left=%defaultroute | |
429 | leftsubnet=10.1.0.0/16 | |
430 | leftcert=moonCert.pem | |
431 | right=%any | |
432 | auto=add | |
433 | ||
434 | Configuration on roadwarrior carol: | |
435 | ||
436 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
437 | ||
438 | /etc/ipsec.d/certs/carolCert.pem | |
439 | ||
440 | /etc/ipsec.secrets: | |
441 | ||
442 | : RSA carolKey.pem "<optional passphrase>" | |
443 | ||
444 | /etc/ipsec.conf: | |
445 | ||
446 | conn home | |
447 | left=%defaultroute | |
448 | leftcert=carolCert.pem | |
449 | right=192.168.0.1 | |
450 | rightsubnet=10.1.0.0/16 | |
451 | rightid="C=CH, O=Linux strongSwan, CN=moon.strongswan.org" | |
452 | auto=start | |
453 | ||
454 | ||
455 | 2.6 Roadwarrior case with virtual IP | |
456 | -------------------------------- | |
457 | ||
458 | Roadwarriors usually have dynamic IP addresses assigned by the ISP they are | |
459 | currently attached to. In order to simplify the routing from moon-net back | |
460 | to the remote access client carol it would be desirable if the roadwarrior had | |
461 | an inner IP address chosen from a pre-assigned pool. | |
462 | ||
463 | 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x | -- 10.3.0.1 | |
464 | moon-net moon carol virtual IP | |
465 | ||
466 | This virtual IP address can be assigned to a strongSwan roadwarrior by adding | |
467 | the parameter | |
468 | ||
469 | leftsourceip=10.3.0.1 | |
470 | ||
471 | to the roadwarrior's ipsec.conf. Of course the virtual IP of each roadwarrior | |
472 | must be distinct. In our example it is chosen from the address pool | |
473 | ||
474 | rightsubnetwithin=10.3.0.0/16 | |
475 | ||
476 | which can be added to the gateway's ipsec.conf so that a single connection | |
477 | definition can handle multiple roadwarriors. | |
478 | ||
479 | Configuration on gateway moon: | |
480 | ||
481 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
482 | ||
483 | /etc/ipsec.d/certs/moonCert.pem | |
484 | ||
485 | /etc/ipsec.secrets: | |
486 | ||
487 | : RSA moonKey.pem "<optional passphrase>" | |
488 | ||
489 | /etc/ipsec.conf: | |
490 | ||
491 | conn rw | |
492 | left=%defaultroute | |
493 | leftsubnet=10.1.0.0/16 | |
494 | leftcert=moonCert.pem | |
495 | right=%any | |
496 | rightsubnetwithin=10.3.0.0/16 | |
497 | auto=add | |
498 | ||
499 | Configuration on roadwarrior carol: | |
500 | ||
501 | /etc/ipsec.d/cacerts/strongswanCert.pem | |
502 | ||
503 | /etc/ipsec.d/certs/carolCert.pem | |
504 | ||
505 | /etc/ipsec.secrets: | |
506 | ||
507 | : RSA carolKey.pem "<optional passphrase>" | |
508 | ||
509 | /etc/ipsec.conf: | |
510 | ||
511 | conn home | |
512 | left=%defaultroute | |
513 | leftsourceip=10.3.0.1 | |
514 | leftcert=carolCert.pem | |
515 | right=192.168.0.1 | |
516 | rightsubnet=10.1.0.0/16 | |
517 | rightid="C=CH, O=Linux strongSwan, CN=moon.strongswan.org" | |
518 | auto=start | |
519 | ||
520 | ||
521 | 3. Generating certificates and CRLs with OpenSSL | |
522 | --------------------------------------------- | |
523 | ||
524 | This section is not a full-blown tutorial on how to use OpenSSL. It just lists | |
525 | a few points that are relevant if you want to generate your own certificates | |
526 | and CRLs for use with strongSwan. | |
527 | ||
528 | ||
529 | 3.1 Generating a CA certificate | |
530 | --------------------------- | |
531 | ||
532 | The OpenSSL statement | |
533 | ||
534 | openssl req -x509 -days 1460 -newkey rsa:2048 \ | |
535 | -keyout strongswanKey.pem -out strongswanCert.pem | |
536 | ||
537 | creates a 2048 bit RSA private key strongswanKey.pem and a self-signed CA | |
538 | certificate strongswanCert.pem with a validity of 4 years (1460 days). | |
539 | ||
540 | openssl x509 -in cert.pem -noout -text | |
541 | ||
542 | lists the properties of a X.509 certificate cert.pem. It allows you to verify | |
543 | whether the configuration defaults in openssl.cnf have been inserted correctly. | |
544 | ||
545 | If you prefer the CA certificate to be in binary DER format then the following | |
546 | command achieves this transformation: | |
547 | ||
548 | openssl x509 -in strongswanCert.pem -outform DER -out strongswanCert.der | |
549 | ||
550 | The directory /etc/ipsec.d/cacerts contains all required CA certificates either | |
551 | in binary DER or in base64 PEM format. Irrespective of the file suffix, Pluto | |
552 | "automagically" determines the correct format. | |
553 | ||
554 | ||
555 | 3.2 Generating a host or user certificate | |
556 | ------------------------------------- | |
557 | ||
558 | The OpenSSL statement | |
559 | ||
560 | openssl req -newkey rsa:1024 -keyout hostKey.pem \ | |
561 | -out hostReq.pem | |
562 | ||
563 | generates a 1024 bit RSA private key hostKey.pem and a certificate request | |
564 | hostReq.pem which has to be signed by the CA. | |
565 | ||
566 | If you want to add a subjectAltName field to the host certificate you must edit | |
567 | the OpenSSL configuration file openssl.cnf and add the following line in the | |
568 | [ usr_cert ] section: | |
569 | ||
570 | subjectAltName=DNS:moon.strongswan.org | |
571 | ||
572 | if you want to identify the host by its Fully Qualified Domain Name (FQDN ), or | |
573 | ||
574 | subjectAltName=IP:192.168.0.1 | |
575 | ||
576 | if you want the ID to be of type IPV4_ADDR. Of course you could include both | |
577 | ID types with | |
578 | ||
579 | subjectAltName=DNS:moon.strongswan.org,IP:192.168.0.1 | |
580 | ||
581 | but the use of an IP address for the identification of a host should be | |
582 | discouraged anyway. | |
583 | ||
584 | For user certificates the appropriate ID type is USER_FQDN which can be | |
585 | specified as | |
586 | ||
587 | subjectAltName=email:carol@strongswan.org | |
588 | ||
589 | or if the user's e-mail address is part of the subject's distinguished name | |
590 | ||
591 | subjectAltName=email:copy | |
592 | ||
593 | Now the certificate request can be signed by the CA with the command | |
594 | ||
595 | openssl ca -in hostReq.pem -days 730 -out hostCert.pem -notext | |
596 | ||
597 | If you omit the -days option then the default_days value (365 days) specified | |
598 | in openssl.cnf is used. The -notext option avoids that a human readable | |
599 | listing of the certificate is prepended to the base64 encoded certificate | |
600 | body. | |
601 | ||
602 | If you want to use the dynamic CRL fetching feature described in section 4.7 | |
603 | then you may include one or several crlDistributionPoints in your end | |
604 | certificates. This can be done in the [ usr_cert ] section of the openssl.cnf | |
605 | configuration file: | |
606 | ||
607 | crlDistributionPoints= @crl_dp | |
608 | ||
609 | [ crl_dp ] | |
610 | ||
611 | URI.1="http://crl.strongswan.org/strongswan.crl" | |
612 | URI.2="ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=Linux strongSwan | |
613 | , c=CH?certificateRevocationList" | |
614 | ||
615 | If you have only a single http distribution point then the short form | |
616 | ||
617 | crlDistributionPoints="URI:http://crl.strongswan.org/strongswan.crl" | |
618 | ||
619 | also works. Due to a known bug in OpenSSL this notation fails with ldap URIs. | |
620 | ||
621 | Usually a Windows-based VPN client needs its private key, its host or | |
622 | user certificate, and the CA certificate. The most convenient way to load | |
623 | this information is to put everything into a PKCS#12 file: | |
624 | ||
625 | openssl pkcs12 -export -inkey carolKey.pem \ | |
626 | -in carolCert.pem -name "carol" \ | |
627 | -certfile strongswanCert.pem -caname "strongSwan Root CA" \ | |
628 | -out carolCert.p12 | |
629 | ||
630 | ||
631 | 3.3 Generating a CRL | |
632 | ---------------- | |
633 | ||
634 | An empty CRL that is signed by the CA can be generated with the command | |
635 | ||
636 | openssl ca -gencrl -crldays 15 -out crl.pem | |
637 | ||
638 | If you omit the -crldays option then the default_crl_days value (30 days) | |
639 | specified in openssl.cnf is used. | |
640 | ||
641 | If you prefer the CRL to be in binary DER format then this conversion | |
642 | can be achieved with | |
643 | ||
644 | openssl crl -in crl.pem -outform DER -out cert.crl | |
645 | ||
646 | The directory /etc/ipsec.d/crls contains all CRLs either in binary DER | |
647 | or in base64 PEM format. Irrespective of the file suffix, Pluto | |
648 | "automagically" determines the correct format. | |
649 | ||
650 | ||
651 | 3.4 Revoking a certificate | |
652 | ---------------------- | |
653 | ||
654 | A specific host certificate stored in the file host.pem is revoked with the | |
655 | command | |
656 | ||
657 | openssl ca -revoke host.pem | |
658 | ||
659 | Next the CRL file must be updated | |
660 | ||
661 | openssl ca -gencrl -crldays 60 -out crl.pem | |
662 | ||
663 | The content of the CRL file can be listed with the command | |
664 | ||
665 | openssl crl -in crl.pem -noout -text | |
666 | ||
667 | in the case of a base64 CRL, or alternatively for a CRL in DER format | |
668 | ||
669 | openssl crl -inform DER -in cert.crl -noout -text | |
670 | ||
671 | ||
672 | ||
673 | 4. Configuring the connections - ipsec.conf | |
674 | ---------------------------------------- | |
675 | ||
676 | 4.1 Configuring my side | |
677 | ------------------- | |
678 | ||
679 | Usually the local side is the same for all connections. Therefore it makes | |
680 | sense to put the definitions characterizing the strongSwan security gateway into | |
681 | the conn %default section of the configuration file /etc/ipsec.conf. If we | |
682 | assume throughout this document that the strongSwan security gateway is left and | |
683 | the peer is right then we can write | |
684 | ||
685 | conn %default | |
686 | # my side is left - the freeswan security gateway | |
687 | left=%defaultroute | |
688 | leftcert=moonCert.pem | |
689 | # load connection definitions automatically | |
690 | auto=add | |
691 | ||
692 | The X.509 certificate by which the strongSwan security gateway will authenticate | |
693 | itself by sending it in binary form to its peers as part of the Internet Key | |
694 | Exchange (IKE) is specified in the line | |
695 | ||
696 | leftcert=moonCert.pem | |
697 | ||
698 | The certificate can either be stored in base64 PEM-format or in the binary | |
699 | DER-format. Irrespective of the file suffix, Pluto "automagically" determines | |
700 | the correct format. Therefore | |
701 | ||
702 | leftcert=moonCert.der | |
703 | ||
704 | or | |
705 | ||
706 | leftcert=moonCert.cer | |
707 | ||
708 | would also be valid alternatives. | |
709 | ||
710 | When using relative pathnames as in the examples above, the certificate files | |
711 | must be stored in in the directory /etc/ipsec.d/certs. In order to distinguish | |
712 | strongSwan's own certificates from locally stored trusted peer certificates | |
713 | (see section 5.5 for details), they could also be stored in a subdirectory | |
714 | below /etc/ipsec.d/certs as e.g. in | |
715 | ||
716 | leftcert=mycerts/moonCert.pem | |
717 | ||
718 | Absolute pathnames are also possible as in | |
719 | ||
720 | leftcert=/usr/ssl/certs/moonCert.pem | |
721 | ||
722 | As an ID for the VPN gateway we recommend the use of a Fully Qualified Domain | |
723 | Name (FQDN) of the form | |
724 | ||
725 | conn rw | |
726 | right=%any | |
727 | leftid=@moon.strongswan.org | |
728 | ||
729 | Important: When an FQDN identifier is used it must be explicitly included as a | |
730 | so called subjectAltName of type dnsName (DNS:) in the certificate indicated | |
731 | by leftcert. For details on how to generate certificates with subjectAltNames, | |
732 | please refer to section 7.2. | |
733 | ||
734 | If you don't want to mess with subjectAltNames, you can use the certificate's | |
735 | Distinguished Name (DN) instead, which is an identifier of type DER_ASN1_DN | |
736 | and which can be written e.g. in the LDAP-type format | |
737 | ||
738 | conn rw | |
739 | right=%any | |
740 | leftid="C=CH, O=Linux strongSwan, CN=moon.strongswan.org" | |
741 | ||
742 | Since the subject's DN is part of the certificate, the leftid does not have to | |
743 | be declared explicitly. Thus the entry | |
744 | ||
745 | conn rw | |
746 | right=%any | |
747 | ||
748 | automatically assumes the subject DN of leftcert to be the host ID. | |
749 | ||
750 | ||
751 | 4.2 Multiple certificates | |
752 | --------------------- | |
753 | ||
754 | strongSwan supports multiple local host certificates and corresponding | |
755 | RSA private keys: | |
756 | ||
757 | conn rw1 | |
758 | right=%any | |
759 | rightid=@peer1.domain1 | |
760 | leftcert=myCert1.pem | |
761 | # leftid is DN of myCert1 | |
762 | ||
763 | conn rw2 | |
764 | right=%any | |
765 | rightid=@peer2.domain2 | |
766 | leftcert=myCert2.pem | |
767 | # leftid is DN of myCert2 | |
768 | ||
769 | When peer1 initiates a connection then strongSwan will send myCert1 and will | |
770 | sign with myKey1 defined in /etc/ipsec.secrets (see section 6.2) whereas | |
771 | myCert2 and myKey2 will be used in a connection setup started from peer2. | |
772 | ||
773 | ||
774 | 4.3 Configuring the peer side using CA certificates | |
775 | ----------------------------------------------- | |
776 | ||
777 | Now we can proceed to define our connections. In many applications we might | |
778 | have dozens of mostly Windows-based road warriors connecting to a central | |
779 | strongSwan security gateway. The following most simple statement: | |
780 | ||
781 | conn rw | |
782 | right=%any | |
783 | ||
784 | defines the general roadwarrior case. The line right=%any literally means that | |
785 | any IPSec peer is accepted, regardless of its current IP source address and its | |
786 | ID, as long as the peer presents a valid X.509 certificate signed by a CA the | |
787 | strongSwan security gateway puts explicit trust in. Additionally the signature | |
788 | during IKE main mode gives proof that the peer is in possession of the private | |
789 | RSA key matching the public key contained in the transmitted certificate. | |
790 | ||
791 | The ID by which a peer is identifying itself during IKE main mode can by any of | |
792 | the ID types IPV4_ADDR, FQDN, USER_FQDN or DER_ASN1_DN. If one of the first | |
793 | three ID types is used, then the accompanying X.509 certificate of the peer | |
794 | must contain a matching subjectAltName field of the type ipAddress (IP:), | |
795 | dnsName (DNS:) or rfc822Name (email:), respectively. With the fourth type | |
796 | DER_ASN1_DN the identifier must completely match the subject field of the | |
797 | peer's certificate. One of the two possible representations of a | |
798 | Distinguished Name (DN) is the LDAP-type format | |
799 | ||
800 | rightid="C=CH, O=Linux strongSwan, CN=sun.strongswan.org" | |
801 | ||
802 | Additional whitespace can be added everywhere as desired since it will be | |
803 | automatically eliminated by the X.509 parser. An exception is the single | |
804 | whitespace between individual words , like e.g. in Linux strongSwan, which is | |
805 | preserved by the parser. | |
806 | ||
807 | The Relative Distinguished Names (RDNs) can alternatively be separated by a | |
808 | slash '/' instead of a comma ',' | |
809 | ||
810 | rightid="/C=CH/O=Linux strongSwan/CN=sun.strongswan.org" | |
811 | ||
812 | This is the representation extracted from the certificate by the OpenSSL | |
813 | command line option | |
814 | ||
815 | openssl x509 -in sunCert.pem -noout -subject | |
816 | ||
817 | The following RDNs are supported by strongSwan | |
818 | ||
819 | +---------------------------------------------------+ | |
820 | | DC Domain Component | | |
821 | |---------------------------------------------------| | |
822 | | C Country | | |
823 | |---------------------------------------------------| | |
824 | | ST State or province | | |
825 | |---------------------------------------------------| | |
826 | | L Locality or town | | |
827 | |---------------------------------------------------| | |
828 | | O Organisation | | |
829 | |---------------------------------------------------| | |
830 | | OU Organisational Unit | | |
831 | |---------------------------------------------------| | |
832 | | CN Common Name | | |
833 | |---------------------------------------------------| | |
834 | | ND NameDistinguisher, used with CN | | |
835 | |---------------------------------------------------| | |
836 | | N Name | | |
837 | |---------------------------------------------------| | |
838 | | G Given name | | |
839 | |---------------------------------------------------| | |
840 | | S Surname | | |
841 | |---------------------------------------------------| | |
842 | | I Initials | | |
843 | |---------------------------------------------------| | |
844 | | T Personal title | | |
845 | |---------------------------------------------------| | |
846 | | E E-mail | | |
847 | |---------------------------------------------------| | |
848 | | Email E-mail | | |
849 | |---------------------------------------------------| | |
850 | | emailAddress E-mail | | |
851 | |---------------------------------------------------| | |
852 | | SN Serial number | | |
853 | |---------------------------------------------------| | |
854 | | serialNumber Serial number | | |
855 | |---------------------------------------------------| | |
856 | | D Description | | |
857 | |---------------------------------------------------| | |
858 | | ID X.500 Unique Identifier | | |
859 | |---------------------------------------------------| | |
860 | | UID User ID | | |
861 | |---------------------------------------------------| | |
862 | | TCGID [Siemens] Trust Center Global ID | | |
863 | |---------------------------------------------------| | |
864 | | unstructuredName Unstructured Name | | |
865 | |---------------------------------------------------| | |
866 | | UN Unstructured Name | | |
867 | |---------------------------------------------------| | |
868 | | employeeNumber Employee Number | | |
869 | |---------------------------------------------------| | |
870 | | EN Employee Number | | |
871 | +---------------------------------------------------+ | |
872 | ||
873 | With the roadwarrior connection definition listed above, an IPsec SA for | |
874 | the strongSwan security gateway moon.strongswan.org itself can be established. | |
875 | If any roadwarrior should be able to reach e.g. the two subnets 10.1.0.0/24 | |
876 | and 10.1.3.0/24 behind the security gateway then the following connection | |
877 | definitions will make this possible | |
878 | ||
879 | conn rw1 | |
880 | right=%any | |
881 | leftsubnet=10.1.0.0/24 | |
882 | ||
883 | conn rw3 | |
884 | right=%any | |
885 | leftsubnet=10.1.3.0/24 | |
886 | ||
887 | If not all peers in possession of a X.509 certificate signed by a specific | |
888 | certificate authority shall be given access to the Linux security gateway, | |
889 | then either a subset of them can be barred by listing the serial numbers of | |
890 | their certificates in a certificate revocation list (CRL) as specified in | |
891 | section 5.2 or as an alternative, access can be controlled by explicitly | |
892 | putting a roadwarrior entry for each eligible peer into ipsec.conf: | |
893 | ||
894 | conn sun | |
895 | right=%any | |
896 | rightid=@sun.strongswan.org | |
897 | ||
898 | conn carol | |
899 | right=%any | |
900 | rightid=carol@strongswan.org | |
901 | ||
902 | conn dave | |
903 | right=%any | |
904 | rightid="C=CH, O=Linux strongSwan, CN=dave@strongswan.org" | |
905 | ||
906 | When the IP address of a peer is known to be stable, it can be specified as | |
907 | well. This entry is mandatory when the strongSwan host wants to act as the | |
908 | initiator of an IPSec connection. | |
909 | ||
910 | conn sun | |
911 | right=192.168.0.2 | |
912 | rightid=@sun.strongswan.org | |
913 | ||
914 | conn carol | |
915 | right=192.168.0.100 | |
916 | rightid=carol@strongswan.org | |
917 | ||
918 | conn dave | |
919 | right=192.168.0.200 | |
920 | rightid="C=CH, O=Linux strongSwan, CN=dave@strongswan.org" | |
921 | ||
922 | conn venus | |
923 | right=192.168.0.50 | |
924 | ||
925 | In the last example the ID types FQDN, USER_FQDN, DER_ASN1_DN and IPV4_ADDR, | |
926 | respectively, were used. Of course all connection definitions presented so far | |
927 | have included the lines in the conn %defaults section, comprising among other | |
928 | a left and leftcert entry. | |
929 | ||
930 | ||
931 | 4.4 Handling Virtual IPs and wildcard subnets | |
932 | ----------------------------------------- | |
933 | ||
934 | Often roadwarriors are behind NAT-boxes with IPsec passthrough, which causes | |
935 | the inner IP source address of an IPsec tunnel to be different from the | |
936 | outer IP source address usually assigned dynamically by the ISP. | |
937 | Whereas the varying outer IP address can be handled by the right=%any | |
938 | construct, the inner IP address or subnet must always be declared in a | |
939 | connection definition. Therefore for the three roadwarriors rw1 to rw3 | |
940 | connecting to a strongSwan security gateway the following entries are | |
941 | required in /etc/ipsec.conf: | |
942 | ||
943 | conn rw1 | |
944 | right=%any | |
945 | righsubnet=10.4.0.5/32 | |
946 | ||
947 | conn rw2 | |
948 | right=%any | |
949 | rightsubnet=10.4.0.47/32 | |
950 | ||
951 | conn rw3 | |
952 | right=%any | |
953 | rightsubnet=10.4.0.128/28 | |
954 | ||
955 | With the wildcard parameter rightsubnetwithin these three entries can be | |
956 | reduced to the single connection definition | |
957 | ||
958 | conn rw | |
959 | right=%any | |
960 | rightsubnetwithin=10.4.0.0/24 | |
961 | ||
962 | Any host will be accepted (of course after successful authentication based on | |
963 | the peer's X.509 certificate only) if it declares a client subnet lying totally | |
964 | within the brackets defined by the wildcard subnet definition (in our example | |
965 | 10.4.0.0/24). For each roadwarrior a connection instance tailored to the | |
966 | subnet of the particular client will be created,based on the generic | |
967 | rightsubnetwithin template. | |
968 | ||
969 | This strongSwan feature can also be helpful with VPN clients getting a | |
970 | dynamically assigned inner IP from a DHCP server located on the NAT router box. | |
971 | ||
972 | ||
973 | 4.5 Protocol and Port Selectors | |
974 | --------------------------- | |
975 | ||
976 | strongSwan offer the possibility to restrict the protocol and optionally the | |
977 | ports in an IPsec SA using the rightprotoport and leftprotoport parameters. | |
978 | ||
979 | Some examples: | |
980 | ||
981 | conn icmp | |
982 | right=%any | |
983 | rightprotoport=icmp | |
984 | left=%defaultroute | |
985 | leftid=@moon.strongswan.org | |
986 | leftprotoport=icmp | |
987 | ||
988 | conn http | |
989 | right=%any | |
990 | rightprotoport=6 | |
991 | left=%defaultroute | |
992 | leftid=@moon.strongswan.org | |
993 | leftprotoport=6/80 | |
994 | ||
995 | conn l2tp # with port wildcard for Mac OS X Panther interoperability | |
996 | right=%any | |
997 | rightprotoport=17/%any | |
998 | left=%defaultroute | |
999 | leftid=@moon.strongswan.org | |
1000 | leftprotoport=17/1701 | |
1001 | ||
1002 | conn dhcp | |
1003 | right=%any | |
1004 | rightprotoport=udp/bootpc | |
1005 | left=%defaultroute | |
1006 | leftid=@moon.strongswan.org | |
1007 | leftsubnet=0.0.0.0/0 #allows DHCP discovery broadcast | |
1008 | leftprotoport=udp/bootps | |
1009 | rekey=no | |
1010 | keylife=20s | |
1011 | rekeymargin=10s | |
1012 | auto=add | |
1013 | ||
1014 | Protocols and ports can be designated either by their numerical values | |
1015 | or by their acronyms defined in /etc/services. | |
1016 | ||
1017 | ipsec status | |
1018 | ||
1019 | shows the following connection definitions: | |
1020 | ||
1021 | "icmp": 192.168.0.1[@moon.strongswan.org]:1/0...%any:1/0 | |
1022 | "http": 192.168.0.1[@moon.strongswan.org]:6/80...%any:6/0 | |
1023 | "l2tp": 192.168.0.1[@moon.strongswan.org]:17/1701...%any:17/%any | |
1024 | "dhcp": 0.0.0.0/0===192.168.0.1[@moon.strongswan.org]:17/67...%any:17/68 | |
1025 | ||
1026 | Based on the protocol and port selectors appropriate eroutes will be set | |
1027 | up, so that only the specified payload types will pass through the IPsec | |
1028 | tunnel. | |
1029 | ||
1030 | ||
1031 | 4.6 IPsec policies based on wildcards | |
1032 | --------------------------------- | |
1033 | ||
1034 | In large VPN-based remote access networks there is often a requirement that | |
1035 | access to the various parts of an internal network must be granted selectively, | |
1036 | e.g. depending on the group membership of the remote access user. strongSwan | |
1037 | makes this possible by applying wildcard filtering on the VPN user's | |
1038 | distinguished name (ID_DER_ASN1_DN). | |
1039 | ||
1040 | Let's make a practical example: | |
1041 | ||
1042 | An organization has a sales department (OU=Sales) and a research group | |
1043 | (OU=Research). In the company intranet there are separate subnets for Sales | |
1044 | (10.0.0.0/24) and Research (10.0.1.0/24) but both groups share a common web | |
1045 | server (10.0.2.100). The VPN clients use Virtual IP addresses that are either | |
1046 | assigned statically or via DHCP-over-IPsec. The sales and research departments | |
1047 | use IP addresses from separate DHCP address pools (10.1.0.0/24) and (10.1.1.0/24), | |
1048 | respectively. An X.509 certificate is issued to each employee, containing in its | |
1049 | subject distinguished name the country (C=CH), the company (O=ACME), | |
1050 | the group membership(OU=Sales or OU=Research) and the common name (e.g. | |
1051 | CN=Bart Simpson). | |
1052 | ||
1053 | The IPsec policy defined above can now be enforced with the following three | |
1054 | IPsec security associations: | |
1055 | ||
1056 | conn sales | |
1057 | right=%any | |
1058 | rightid="C=CH, O=ACME, OU=Sales, CN=*" | |
1059 | rightsubnetwithin=10.1.0.0/24 # Sales DHCP range | |
1060 | leftsubnet=10.0.0.0/24 # Sales subnet | |
1061 | ||
1062 | conn research | |
1063 | right=%any | |
1064 | rightid="C=CH, O=ACME, OU=Research, CN=*" | |
1065 | rightsubnetwithin=10.1.1.0/24 # Research DHCP range | |
1066 | leftsubnet=10.0.1.0/24 # Research subnet | |
1067 | ||
1068 | conn web | |
1069 | right=%any | |
1070 | rightid="C=CH, O=ACME, OU=*, CN=*" | |
1071 | rightsubnetwithin=10.1.0.0/23 # Remote access DHCP range | |
1072 | leftsubnet=10.0.2.100/32 # Web server | |
1073 | rightprotoport=tcp # TCP protocol only | |
1074 | leftprotoport=tcp/http # TCP port 80 only | |
1075 | ||
1076 | Of course group specific tunneling could be implemented on the | |
1077 | basis of the Virtual IP range specified by the rightsubnetwithin | |
1078 | parameter alone, but the wildcard matching mechanism guarantees that | |
1079 | only authorized user can access the corresponding subnets. | |
1080 | ||
1081 | The '*' character is used as a wildcard in relative distinguished names (RDNs). | |
1082 | In order to match a wildcard template, the ID_DER_ASN1_DN of a peer must contain | |
1083 | the same number of RDNs (selected from the list in section 4.3) appearing in the | |
1084 | exact order defined by the template. | |
1085 | ||
1086 | "C=CH, O=ACME, OU=Research, OU=Special Effects, CN=Bart Simpson" | |
1087 | ||
1088 | matches the templates | |
1089 | ||
1090 | "C=CH, O=ACME, OU=Research, OU=*, CN=*" | |
1091 | ||
1092 | "C=CH, O=ACME, OU=*, OU=Special Effects, CN=*" | |
1093 | ||
1094 | "C=CH, O=ACME, OU=*, OU=*, CN=*" | |
1095 | ||
1096 | but not the template | |
1097 | ||
1098 | "C=CH, O=ACME, OU=*, CN=*" | |
1099 | ||
1100 | which doesn't have the same number of RDNs. | |
1101 | ||
1102 | ||
1103 | 4.7 IPsec policies based on CA certificates | |
1104 | --------------------------------------- | |
1105 | ||
1106 | As an alternative to the wildcard based IPsec policies described in section 4.6, | |
1107 | access to specific client host and subnets can abe controlled on the basis of | |
1108 | the CA that issued the peer certificate | |
1109 | ||
1110 | ||
1111 | conn sales | |
1112 | right=%any | |
1113 | rightca="C=CH, O=ACME, OU=Sales, CN=Sales CA" | |
1114 | rightsubnetwithin=10.1.0.0/24 # Sales DHCP range | |
1115 | leftsubnet=10.0.0.0/24 # Sales subnet | |
1116 | ||
1117 | conn research | |
1118 | right=%any | |
1119 | rightca="C=CH, O=ACME, OU=Research, CN=Research CA" | |
1120 | rightsubnetwithin=10.1.1.0/24 # Research DHCP range | |
1121 | leftsubnet=10.0.1.0/24 # Research subnet | |
1122 | ||
1123 | conn web | |
1124 | right=%any | |
1125 | rightca="C=CH, O=ACME, CN=ACME Root CA" | |
1126 | rightsubnetwithin=10.1.0.0/23 # Remote access DHCP range | |
1127 | leftsubnet=10.0.2.100/32 # Web server | |
1128 | rightprotoport=tcp # TCP protocol only | |
1129 | leftprotoport=tcp/http # TCP port 80 only | |
1130 | ||
1131 | In the example above, the connection "sales" can be used by peers | |
1132 | presenting certificates issued by the Sales CA, only. In the same way, | |
1133 | the use of the connection "research" is restricted to owners of certificates | |
1134 | issued by the Research CA. The connection "web" is open to both "Sales" and | |
1135 | "Research" peers because the required "ACME Root CA" is the issuer of the | |
1136 | Research and Sales intermediate CAs. If no rightca parameter is present | |
1137 | then any valid certificate issued by one of the trusted CAs in | |
1138 | /etc/ipsec.d/cacerts can be used by the peer. | |
1139 | ||
1140 | The leftca parameter usually doesn't have to be set explicitly because | |
1141 | by default it is set to the issuer field of the certificate loaded via | |
1142 | leftcert. The statement | |
1143 | ||
1144 | rightca=%same | |
1145 | ||
1146 | sets the CA requested from the peer to the CA used by the left side itself | |
1147 | as e.g. in | |
1148 | ||
1149 | conn sales | |
1150 | right=%any | |
1151 | rightca=%same | |
1152 | leftcert=mySalesCert.pem | |
1153 | ||
1154 | ||
1155 | 4.8 Sending certificate requests | |
1156 | ---------------------------- | |
1157 | ||
1158 | The presence of a rightca parameter also causes the CA to be sent as | |
1159 | part of the certificate request message when strongSwan is the initiator. | |
1160 | A special case occurs when strongSwan responds to a roadwarrior. If several | |
1161 | roadwarrior connections based on different CAs are defined then all eligible | |
8c5d72cd | 1162 | CAs will be listed in Pluto�s certificate request message. |
997358a6 MW |
1163 | |
1164 | ||
1165 | 4.9 IPsec policies based on group attributes | |
1166 | ---------------------------------------- | |
1167 | ||
1168 | X.509 attribute certificates are the most powerful mechanism for implementing | |
1169 | IPsec security policies. The rightgroups parameter in a connection definition | |
1170 | restricts the access to members of the listed groups only. An IPsec peer must | |
1171 | have a valid attribute certificate issued by a trusted Authorization Authority | |
1172 | and listing one of the requirede group attributes in order to get admitted. | |
1173 | ||
1174 | conn sales | |
1175 | right=%any | |
1176 | rightgroups="Sales" | |
1177 | rightsubnetwithin=10.1.0.0/24 # Sales DHCP range | |
1178 | leftsubnet=10.0.0.0/24 # Sales subnet | |
1179 | ||
1180 | conn research | |
1181 | right=%any | |
1182 | rightgroups="Research" | |
1183 | rightsubnetwithin=10.1.1.0/24 # Research DHCP range | |
1184 | leftsubnet=10.0.1.0/24 # Research subnet | |
1185 | ||
1186 | conn web | |
1187 | right=%any | |
1188 | rightgroups="Sales, Research" | |
1189 | rightsubnetwithin=10.1.0.0/23 # Remote access DHCP range | |
1190 | leftsubnet=10.0.2.100/32 # Web server | |
1191 | rightprotoport=tcp # TCP protocol only | |
1192 | leftprotoport=tcp/http # TCP port 80 only | |
1193 | ||
1194 | In the examples above membership of the group "Sales" is required for | |
1195 | connection sales and membership of "Research" for connection research | |
1196 | whereas connection web is accessible for both groups. | |
1197 | ||
1198 | Currently the attribute certificates of the peers must be loaded statically | |
1199 | via the /etc/ipsec.d/acerts/ directory. In future releases of strongSwan it | |
1200 | will be possible to fetch them from an LDAP directory server. | |
1201 | ||
1202 | ||
1203 | 5. Configuring certificates and CRLs | |
1204 | --------------------------------- | |
1205 | ||
1206 | ||
1207 | 5.1 Installing the CA certificates | |
1208 | ------------------------------ | |
1209 | ||
1210 | X.509 certificates received by strongSwan during the IKE protocol are | |
1211 | automatically authenticated by going up the trust chain until a self-signed | |
1212 | root CA certificate is reached. Usually host certificates are directly signed | |
1213 | by a root CA, but strongSwan also supports multi-level hierarchies with | |
1214 | intermediate CAs in between. All CA certificates belonging to a trust chain | |
1215 | must be copied in either binary DER or base64 PEM format into the directory | |
1216 | ||
1217 | /etc/ipsec.d/cacerts/ | |
1218 | ||
1219 | ||
1220 | 5.2 Installing optional certificate revocation lists (CRLs) | |
1221 | ------------------------------------------------------- | |
1222 | ||
1223 | By copying a CA certificate into /etc/ipsec.d/cacerts/, automatically all user | |
1224 | or host certificates issued by this CA are declared valid. Unfortunately | |
1225 | private keys might get compromised inadvertently or intentionally, personal | |
1226 | certificates of users leaving a company have to be blocked immediately, etc. | |
1227 | To this purpose certificate revocation lists (CRLs) have been created. CRLs | |
1228 | contain the serial numbers of all user or host certificates that have been | |
1229 | revoked due to various reasons. | |
1230 | ||
1231 | After successful verification of the X.509 trust chain, Pluto searches its | |
1232 | list of CRLs either obtained by loading them from the /etc/ipsec.d/crls/ | |
1233 | directory or fetching them dynamically from a HTTP or LDAP server for the | |
1234 | presence of a CRL issued by the CA that has signed the certificate. | |
1235 | ||
1236 | If the serial number of the certificate is found in the CRL then the public key | |
1237 | contained in the certificate is declared invalid and the IPSec SA will not be | |
1238 | established. If no CRL is found or if the deadline defined in the nextUpdate | |
1239 | field of the CRL has been reached, a warning is issued but the public key will | |
1240 | nevertheless be accepted. CRLs must be stored either in binary DER or base64 PEM | |
1241 | format in the crls directory. Section 7.3 will explain in detail how CRLs can | |
1242 | be created using OpenSSL. | |
1243 | ||
1244 | ||
1245 | 5.3 Dynamic update of certificates and CRLs | |
1246 | --------------------------------------- | |
1247 | ||
1248 | Pluto reads certificates and CRLs from their respective files during system | |
1249 | startup and keeps them in memory in the form of chained lists. X.509 | |
1250 | certificates have a finite life span defined by their validity field. Therefore | |
1251 | it must be possible to replace CA or OCSP certificates kept in system memory | |
1252 | without disturbing established ISAKMP SAs. Certificate revocation lists should | |
1253 | also be updated in the regular intervals indicated by the nextUpdate field in | |
1254 | the CRL body. The following interactive commands allow the manual replacement | |
1255 | of the various files: | |
1256 | ||
1257 | +---------------------------------------------------------------------------+ | |
1258 | | ipsec rereadsecrets reload file /etc/ipsec.secrets | | |
1259 | |---------------------------------------------------------------------------| | |
1260 | | ipsec rereadcacerts reload all files in /etc/ipsec.d/cacerts/ | | |
1261 | |---------------------------------------------------------------------------| | |
1262 | | ipsec rereadaacerts reload all files in /etc/ipsec.d/aacerts/ | | |
1263 | |---------------------------------------------------------------------------| | |
1264 | | ipsec rereadocspcerts reload all files in /etc/ipsec.d/ocspcerts/ | | |
1265 | |---------------------------------------------------------------------------| | |
1266 | | ipsec rereadacerts reload all files in /etc/ipsec.d/acerts/ | | |
1267 | |---------------------------------------------------------------------------| | |
1268 | | ipsec rereadcrls reload all files in /etc/ipsec.d/crls/ | | |
1269 | |---------------------------------------------------------------------------| | |
1270 | | ipsec rereadall ipsec rereadsecrets | | |
1271 | | rereadcacerts | | |
1272 | | rereadaacerts | | |
1273 | | rereadocspcerts | | |
1274 | | rereadacerts | | |
1275 | | rereadcrls | | |
1276 | |---------------------------------------------------------------------------| | |
1277 | | ipsec purgeocsp purge the OCSP cache and fetching requests | | |
1278 | +---------------------------------------------------------------------------+ | |
1279 | ||
1280 | CRLs can also be automatically fetched from an HTTP or LDAP server by using | |
1281 | the CRL distribution points contained in X.509 certificates. The command | |
1282 | ||
1283 | ipsec listcrls | |
1284 | ||
1285 | shows any pending fetch requests: | |
1286 | ||
1287 | Oct 31 00:29:53 2002, trials: 2 | |
1288 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
1289 | distPts: 'http://crl.strongswan.org/strongswan.crl' | |
1290 | 'ldap://ldap.strongswan.org/o=Linux strongSwan, c=CH | |
1291 | ?certificateRevocationList?base | |
1292 | ?(objectClass=certificationAuthority)' | |
1293 | ||
1294 | In the example above, an http and an ldap URL were extracted from a received | |
1295 | end certificate. An independent thread then tries to fetch a CRL from the | |
1296 | designated distribution points. The same thread also periodically checks | |
1297 | if any loaded CRLs are about to expire. The check interval can be defined in | |
1298 | the "config setup" section of the ipsec.conf file: | |
1299 | ||
1300 | config setup | |
1301 | crlcheckinterval=600 | |
1302 | ||
1303 | In our example the thread wakes up every 600 seconds or 10 minutes in order | |
1304 | to check the validity of the CRLs or to retry any pending fetch requests: | |
1305 | ||
1306 | List of X.509 CRLs: | |
1307 | ||
1308 | Dec 19 09:35:31 2002, revoked certs: 40 | |
1309 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
1310 | distPts: 'http://crl.strongswan.org/strongswan.crl' | |
1311 | updates: this Dec 19 09:35:00 2002 | |
1312 | next Dec 19 10:35:00 2002 warning (expires in 19 minutes) | |
1313 | ||
1314 | List of fetch requests: | |
1315 | ||
1316 | Dec 19 10:15:31 2002, trials: 1 | |
1317 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
1318 | distPts: 'http://crl.strongwan.org/strongswan.crl' | |
1319 | ||
1320 | The first trial to update a CRL is started 2*crlcheckinterval before the | |
1321 | nextUpdate time, i.e. when less than 20 minutes are left in our practical | |
1322 | example. When crlcheckinterval is set to 0 (this is also the default value | |
1323 | when the parameter is not set in ipsec.conf) then the CRL checking and updating | |
1324 | thread is not started and dynamic CRL fetching is disabled. | |
1325 | ||
1326 | ||
1327 | 5.4 Local caching of CRLs | |
1328 | --------------------- | |
1329 | ||
1330 | The the ipsec.conf option | |
1331 | ||
1332 | config setup | |
1333 | cachecrls=yes | |
1334 | ||
1335 | activates the local caching of CRLs that were dynamically fetched from an | |
1336 | HTTP or LDAP server. Cached copies are stored in /etc/ipsec.d/crls under a | |
1337 | unique filename formed from the issuer's SubjectKeyIdentifier and the suffix .crl. | |
1338 | ||
1339 | With the cached copy the CRL is immediately available after pluto's startup. | |
1340 | When the local copy is about to expire it is automatically replaced with an | |
1341 | updated CRL fetched from one of the defined CRL distribution points. | |
1342 | ||
1343 | ||
1344 | 5.5 Online Certificate Status Protocol (OCSP) | |
1345 | ----------------------------------------- | |
1346 | ||
1347 | The Online Certificate Status Protocol is defined by RFC 2560. It can be | |
1348 | used to query an OCSP server about the current status of an X.509 certificate | |
1349 | and is often used as a more dynamic alternative to a static Certificate | |
1350 | Revocation List (CRL). Both the OCSP request sent by the client and the OCSP | |
1351 | response messages returned by the server are transported via a standard | |
1352 | TCP/HTTP connection. Therefore cURL support must be enabled in pluto/Makefile: | |
1353 | ||
1354 | # Uncomment this line to enable OCSP fetching using HTTP | |
1355 | LIBCURL=1 | |
1356 | ||
1357 | In the simplest OCSP setup, a default URI under which the OCSP server for a | |
1358 | given CA can be accessed is defined in ipsec.conf: | |
1359 | ||
1360 | config setup | |
1361 | crlcheckinterval=600 | |
1362 | ||
1363 | ca strongswan | |
1364 | cacert=strongswanCert.pem | |
1365 | ocspuri=http://ocsp.strongswan.org:8880 | |
1366 | auto=add | |
1367 | ||
1368 | The HTTP port can be freely chosen. In our example we have assumed TCP port 8880. | |
1369 | The crlcheckinterval must be set to a value different from zero. Otherwise the | |
1370 | OCSP fetching thread will not be started. | |
1371 | ||
1372 | The well-known openssl-0.9.7 package from http://www.openssl.org implements | |
1373 | an OCSP server that can be used in conjunction with an openssl-based Public | |
1374 | Key Infrastructure. The OCSP client integrated into Pluto does not contain | |
1375 | any OpenSSL code though, but is based on the existing ASN.1 functionality of | |
1376 | strongSwan. | |
1377 | ||
1378 | The OpenSSL-based OCSP server is started with the following command: | |
1379 | ||
1380 | openssl ocsp -index index.txt -CA strongswanCert.pem -port 8880 \ | |
1381 | -rkey ocspKey.pem -rsigner ocspCert.pem \ | |
1382 | -resp_no_certs -nmin 60 -text | |
1383 | ||
1384 | The command consists of the parameters | |
1385 | ||
1386 | -index index.txt is a copy of the OpenSSL index file containing the list of | |
1387 | all issued certificates. The certificate status in indext.txt | |
1388 | is designated either by V for valid or R for revoked. If | |
1389 | a new certificate is added or if a certificate is revoked | |
1390 | using the openssl ca command, the OCSP server must be restarted | |
1391 | in order for the changes in index.txt to take effect. | |
1392 | ||
1393 | -CA the CA certificate | |
1394 | ||
1395 | -port the HTTP port the OCSP server is listening on. | |
1396 | ||
1397 | -rkey the private key used to sign the OCSP response. The use of the | |
1398 | sensitive CA private key is not recommended since this could | |
1399 | jeopardize the security of your production PKI if the OCSP | |
1400 | server is hacked. It is much better to generate a special | |
1401 | RSA private key just for OCSP signing use instead. | |
1402 | ||
1403 | -rsigner the certificate of the OCSP server containing a public key which | |
1404 | matches the private key defined by -rkey and which can be used by | |
1405 | the client to check the trustworthiness of the signed OCSP response. | |
1406 | ||
1407 | -resp_no_certs With this option the OCSP signer certificate defined by | |
1408 | -rsigner is not included in the OCSP response. | |
1409 | ||
1410 | -nmin the validity interval of an OCSP response given in minutes. | |
1411 | 2*crlcheckinterval before the expiration of the OCSP responses, | |
1412 | a new query will by pro-actively started by the Pluto fetching thread. | |
1413 | ||
1414 | If nmin is missing or set to zero then the default validity interval | |
1415 | compiled into Pluto will be 2 minutes, leading to a quasi one-time | |
1416 | use of the OCSP status response which will not be periodically | |
1417 | refreshed by the fetching thread. In conjunction with the parameter | |
1418 | setting "strictcrlpolicy=yes" a real-time certificate status query | |
1419 | can be implemented in this way. | |
1420 | ||
1421 | -text This option activates a verbose logging output, showing the contents | |
1422 | of both the received OCSP request and sent OCSP response. | |
1423 | ||
1424 | How does Pluto get hold of the OCSP signer certificate? There are two | |
1425 | possibilities: | |
1426 | ||
1427 | Either you put the OCSP certificate into the default directory | |
1428 | ||
1429 | /etc/ipsec.d/ocspcerts | |
1430 | ||
1431 | or alternatively Pluto can receive it as part of the OCSP response from the | |
1432 | remote OCSP server. In the latter case, how can Pluto make sure that | |
1433 | the server has indeed been authorized by the CA to deal out certificate status | |
1434 | information? In order to ascertain the OCSP signer capability, an extended | |
1435 | key usage attribute can be included in the OCSP server certificate. Just | |
1436 | insert the parameter | |
1437 | ||
1438 | extendedKeyUsage=OCSPSigner | |
1439 | ||
1440 | in the [ usr_cert ] section of your openssl.cnf configuration file before | |
1441 | the CA signs the OCSP server certificate. | |
1442 | ||
1443 | For a given CA the corresponding ca section in ipsec.conf (see section 7) allows | |
1444 | to define the URI of a single OCSP server. As an alternative an OCSP URI can be | |
1445 | embedded into each host and user certificate by putting the line | |
1446 | ||
1447 | authorityInfoAccess = OCSP;URI:http://ocsp.strongswan.org:8880 | |
1448 | ||
1449 | into the [ usr_cert ] section of your openssl.cnf configuration file. | |
1450 | If an OCSP authorityInfoAccess extension is present in a certificate then this | |
1451 | record overrides the default URI defined by the ca section. | |
1452 | ||
1453 | ||
1454 | 5.6 CRL Policy | |
1455 | ---------- | |
1456 | ||
1457 | By default Pluto is quite tolerant concerning the handling of CRLs. It is not | |
1458 | mandatory for a CRL to be present in /etc/ipsec.d/crls and if the expiration | |
1459 | date defined by the nextUpdate field of a CRL has been reached just a warning | |
1460 | is issued but a peer certificate will always be accepted if it has not been | |
1461 | revoked. | |
1462 | ||
1463 | If you want to enforce a stricter CRL policy then you can do this by setting | |
1464 | the "strictcrlpolicy" option. This is done in the "config setup" section | |
1465 | of the ipsec.conf file: | |
1466 | ||
1467 | config setup | |
1468 | strictcrlpolicy=yes | |
1469 | ... | |
1470 | ||
1471 | A certificate received from a peer will not be accepted if no corresponding | |
1472 | CRL or OCSP response is available. And if an ISAKMP SA re-negotiation takes | |
1473 | place after the nextUpdate deadline has been reached, the peer certificate | |
1474 | will be declared invalid and the cached RSA public key will be deleted, causing | |
1475 | the connection in question to fail. Therefore if you are going to use the | |
1476 | "strictcrlpolicy=yes" option, make sure that the CRLs will always be updated | |
1477 | in time. Otherwise a total standstill would ensue. | |
1478 | ||
1479 | As mentioned earlier the default setting is "strictcrlpolicy=no" | |
1480 | ||
1481 | ||
1482 | 5.7 Configuring the peer side using locally stored certificates | |
1483 | ----------------------------------------------------------- | |
1484 | ||
1485 | If you don't want to use trust chains based on CA certificates as proposed in | |
1486 | section 4.3 you can alternatively import trusted peer certificates directly | |
1487 | into Pluto. Thus you do not have to rely on the certificate to be transmitted | |
1488 | by the peer as part of the IKE protocol. | |
1489 | ||
1490 | With the conn %default section defined in section 4.1 and the use of the | |
1491 | rightcert keyword for the peer side, the connection definitions in section 4.3 | |
1492 | can alternatively be written as | |
1493 | ||
1494 | conn sun | |
1495 | right=%any | |
1496 | rightid=@sun.strongswan.org | |
1497 | rightcert=sunCert.cer | |
1498 | ||
1499 | conn carol | |
1500 | right=192.168.0.100 | |
1501 | rightcert=carolCert.der | |
1502 | ||
1503 | If the peer certificates are loaded locally then there is no sense in sending | |
1504 | any certificates to the other end via the IKE Main Mode protocol. Especially | |
1505 | if self-signed certificates are used which wouldn't be accepted any way by | |
1506 | the other side. In these cases it is recommended to add | |
1507 | ||
123fdf70 | 1508 | leftsendcert=never |
997358a6 MW |
1509 | |
1510 | to the connection definition[s] in order to avoid the sending of the host's | |
1511 | own certificate. The default value is | |
1512 | ||
123fdf70 AS |
1513 | leftsendcert=ifasked |
1514 | ||
1515 | If a peer does not send a certificate request then use the setting | |
1516 | ||
1517 | leftsendcert=always | |
997358a6 MW |
1518 | |
1519 | If a peer certificate contains a subjectAltName extension, then an alternative | |
1520 | rightid type can be used, as the example "conn sun" shows. If no rightid | |
1521 | entry is present then the subject distinguished name contained in the | |
1522 | certificate is taken as the ID. | |
1523 | ||
1524 | Using the same rules concerning pathnames that apply to strongSwan's own | |
1525 | certificates, the following two definitions are also valid for trusted peer | |
1526 | certificates: | |
1527 | ||
1528 | rightcert=peercerts/carolCert.der | |
1529 | ||
1530 | or | |
1531 | ||
1532 | rightcert=/usr/ssl/certs/carolCert.der | |
1533 | ||
1534 | ||
1535 | 6. Installing the private key - ipsec.secrets | |
1536 | ------------------------------------------ | |
1537 | ||
1538 | 6.1 Loading private key files in PKCS#1 format | |
1539 | ------------------------------------------ | |
1540 | ||
1541 | Besides strongSwan's raw private key format strongSwan has been enabled to | |
1542 | load RSA private keys in the PKCS#1 file format. The key files can be | |
1543 | optionally secured with a passphrase. | |
1544 | ||
1545 | RSA private key files are declared in /etc/ipsec.secrets using the syntax | |
1546 | ||
1547 | : RSA <my keyfile> "<optional passphrase>" | |
1548 | ||
1549 | The key file can be either in base64 PEM-format or binary DER-format. The | |
1550 | actual coding is detected "automagically" by Pluto. The example | |
1551 | ||
1552 | : RSA moonKey.pem | |
1553 | ||
1554 | uses a relative pathname. In this case Pluto will look for the key file | |
1555 | in the directory | |
1556 | ||
1557 | /etc/ipsec.d/private | |
1558 | ||
1559 | As an alternative an absolute pathname can be given as in | |
1560 | ||
1561 | : RSA /usr/ssl/private/moonKey.pem | |
1562 | ||
1563 | In both cases make sure that the key files are root readable only. | |
1564 | ||
1565 | Often a private key must be transported from the Certification Authority | |
1566 | where it was generated to the target security gateway where it is going | |
1567 | to be used. In order to protect the key it can be encrypted with 3DES | |
1568 | using a symmetric transport key derived from a cryptographically strong | |
1569 | passphrase. | |
1570 | ||
1571 | openssl genrsa -des3 -out moonKey.pem 1024 | |
1572 | ||
1573 | Because of the weak security, key files protected by single DES will not | |
1574 | be accepted by Pluto!!! | |
1575 | ||
1576 | Once on the security gateway the private key can either be permanently | |
1577 | unlocked so that it can be used by Pluto without having to know a | |
1578 | passphrase | |
1579 | ||
1580 | openssl rsa -in moonKey.pem -out moonKey.pem | |
1581 | ||
1582 | or as an option the key file can remain secured. In this case the passphrase | |
1583 | unlocking the private key must be added after the pathname in | |
1584 | /etc/ipsec.secrets | |
1585 | ||
1586 | : RSA moonKey.pem "This is my passphrase" | |
1587 | ||
1588 | Some CAs distribute private keys embedded in a PKCS#12 file. Since Pluto | |
1589 | is not able yet to read this format directly, the private key part must | |
1590 | first be extracted using the command | |
1591 | ||
1592 | openssl pkcs12 -nocerts -in moonCert.p12 -out moonKey.pem | |
1593 | ||
1594 | if the key file moonKey.pem is to be secured again by a passphrase, or | |
1595 | ||
1596 | openssl pkcs12 -nocerts -nodes -in moonCert.p12 -out moonKey.pem | |
1597 | ||
1598 | if the private key is to be stored unlocked. | |
1599 | ||
1600 | ||
1601 | 6.2 Entering passphrases interactively | |
1602 | ---------------------------------- | |
1603 | ||
1604 | On a VPN gateway you would want to put the passphrase protecting the private | |
1605 | key file right into /etc/ipsec.secrets as described in the previous paragraph, | |
1606 | so that the gateway can be booted in unattended mode. The risk of keeping | |
1607 | unencrypted secrets on a server can be minimized by putting the box into a | |
1608 | locked room. As long as no one can get root access on the machine the private | |
1609 | keys are safe. | |
1610 | ||
1611 | On a mobile laptop computer the situation is quite different. The computer can | |
1612 | be stolen or the user is leaving it unattended so that unauthorized persons | |
1613 | can get access to it. In theses cases it would be preferable not to keep any | |
1614 | passphrases openly in /etc/ipsec.secrets but to prompt for them interactively | |
1615 | instead. This is easily done by defining | |
1616 | ||
1617 | : RSA moonKey.pem %prompt | |
1618 | ||
1619 | Since strongSwan is usually started during the boot process, usually no | |
1620 | interactive console windows is available which can be used by Pluto to | |
1621 | prompt for the passphrase. This must be initiated by the user by typing | |
1622 | ||
1623 | ipsec secrets | |
1624 | ||
1625 | which actually is an alias for the existing command | |
1626 | ||
1627 | ipsec rereadsecrets | |
1628 | ||
1629 | and which causes the prompt | |
1630 | ||
1631 | need passphrase for '/etc/ipsec.d/private/moonKey.pem' | |
1632 | Enter: | |
1633 | ||
1634 | to appear. If the passphrase was correct and the private key file could be | |
1635 | successfully decrypted then | |
1636 | ||
1637 | valid passphrase | |
1638 | ||
1639 | results. Otherwise the prompt | |
1640 | ||
1641 | invalid passphrase, please try again | |
1642 | Enter: | |
1643 | ||
1644 | will give you another try. Entering a carriage return will abort the | |
1645 | the passphrase prompting. | |
1646 | ||
1647 | ||
1648 | 6.3 Multiple private keys | |
1649 | --------------------- | |
1650 | ||
1651 | strongSwan supports multiple private keys. Since the connections defined | |
1652 | in ipsec.conf can find the correct private key based on the public key | |
1653 | contained in the certificate assigned by leftcert, default private key | |
1654 | definitions without specific IDs can be used | |
1655 | ||
1656 | : RSA myKey1.pem "<optional passphrase1>" | |
1657 | ||
1658 | : RSA myKey2.pem "<optional passphrase2>" | |
1659 | ||
1660 | ||
1661 | 7. Configuring CA properties - ipsec.conf | |
1662 | -------------------------------------- | |
1663 | ||
1664 | Besides the definition of IPsec connections the ipsec.conf file can also | |
1665 | be used to configure a few properties of the certification authorities | |
1666 | needed to establish the X.509 trust chains. The following example shows | |
1667 | the parameters that are currently available: | |
1668 | ||
1669 | ca strongswan | |
1670 | cacert=strongswanCert.pem | |
1671 | ocspuri=http://ocsp.strongswan.org:8880 | |
1672 | crluri=http://crl.strongswan.org/strongswan.crl' | |
1673 | crluri2="ldap:///O=Linux strongSwan, C=CH?certificateRevocationList" | |
1674 | ldaphost=ldap.strongswan.org | |
1675 | auto=add | |
1676 | ||
1677 | In a similar way as conn sections are used for connection definitions, an | |
1678 | arbitrary number of optional ca sections define the basic properties of CAs. | |
1679 | ||
1680 | Each ca section is named with a unique label | |
1681 | ||
1682 | ca strongswan | |
1683 | ||
1684 | The only mandatory parameter is | |
1685 | ||
1686 | cacert=strongswanCert.pem | |
1687 | ||
1688 | which points to the CA certificate which usually resides in the default | |
1689 | directory /etc/ipsec.d/cacerts/ but could also be retrieved via an absolute | |
1690 | path name. If the CA certificate is stored on a smartcard then the | |
1691 | notation | |
1692 | ||
1693 | cacert=%smartcard#<n> | |
1694 | ||
1695 | or alternatively | |
1696 | ||
1697 | cacert=%smartcard<optional slot nr>:<key id> | |
1698 | ||
1699 | can be used. The selection of smartcard slots is described in more detail | |
1700 | in section 8.1. | |
1701 | ||
1702 | From the certificate the CA's distinguished name and the serial number | |
1703 | is extracted. If an optional subjectKeyAuthentifier is present then it can | |
1704 | be used to uniquely identify consecutive generations of CA certificates | |
1705 | carrying the same distinguished name. | |
1706 | ||
1707 | The OCSP URI | |
1708 | ||
1709 | ocspuri=http://ocsp.strongswan.org:8880 | |
1710 | ||
1711 | allows to define an individual OCSP server per CA. Also up to two additional | |
1712 | CRL distribution points (CDPs) can be defined | |
1713 | ||
1714 | crluri=http://crl.strongswan.org/strongswan.crl' | |
1715 | crluri2="ldap:///O=Linux strongSwan, C=CH?certificateRevocationList" | |
1716 | ||
1717 | which are added to any CDPs already present in the received certificates | |
1718 | themselves. The last parameter | |
1719 | ||
1720 | ldaphost=ldap.strongswan.org | |
1721 | ||
1722 | can be used to fill in the actual server name in LDAP CDPs where the host is missing | |
1723 | as e.g. in the crluri2 above. In future releases this ldaphost parameter might be used | |
1724 | to retrieve user, host and attribute certificates. | |
1725 | ||
1726 | ||
1727 | With the auto=add statement the ca definition is automatically loaded into Pluto during | |
1728 | system startup. Setting auto=ignore will ignore the ca section. Additional ca definitions | |
1729 | can be loaded from ipsec.conf during runtime with the command | |
1730 | ||
1731 | ipsec auto --type ca --add strongswan-sales | |
1732 | ||
1733 | and | |
1734 | ||
1735 | ipsec auto --type ca --delete strongswan-sales | |
1736 | ||
1737 | deletes the labeled ca entry. And finally the command | |
1738 | ||
1739 | ipsec auto --type ca --replace strongswan | |
1740 | ||
1741 | first deletes the old definition in Pluto's memory and then loads the updated version | |
1742 | from ipsec.conf. Any parameters which appear in several ca definitions can be put in | |
1743 | a common ca %default section | |
1744 | ||
1745 | ca %default | |
1746 | ldaphost=ldap.strongswan.org | |
1747 | ||
1748 | ||
1749 | 8. Smartcard support | |
1750 | ----------------- | |
1751 | ||
1752 | 8.1 Configuring a smartcard-based connection | |
1753 | ---------------------------------------- | |
1754 | ||
1755 | Defining a smartcard-based connection in ipsec.conf is easy: | |
1756 | ||
1757 | conn sun | |
1758 | right=192.168.0.2 | |
1759 | rightid=@sun.strongswan.org | |
1760 | left=%defaultroute | |
1761 | leftcert=%smartcard | |
1762 | auto=add | |
1763 | ||
1764 | In most cases there is a single smartcard reader or cryptotoken and only one | |
1765 | RSA private key safely stored on the crypto device. Thus usually the entry | |
1766 | ||
1767 | leftcert=%smartcard | |
1768 | ||
1769 | which stands for the full notation | |
1770 | ||
1771 | leftcert=%smartcard#1 | |
1772 | ||
1773 | is sufficient where the first certificate/private key object enumerated by | |
1774 | the PKCS#11 module is used. If several certificate/private key objects are | |
1775 | present then the nth object can be selected using | |
1776 | ||
1777 | leftcert=%smartcard#<n> | |
1778 | ||
1779 | The command | |
1780 | ||
1781 | ipsec listcards | |
1782 | ||
1783 | gives an overview over all certificate objects made available by the PKCS#11 | |
1784 | module.CA certificates are automatically available as trust anchors. | |
1785 | ||
1786 | As an alternative the certificate ID and/or the slot number defined by | |
1787 | the PKCS#11 standard can be specified using the notation | |
1788 | ||
1789 | leftcert=%smartcard<optional slot nr>:<key id in hex format> | |
1790 | ||
1791 | Thus | |
1792 | ||
1793 | leftcert=%smartcard:50 | |
1794 | ||
1795 | will look in all available slots for ID 0x50 starting with the first slot | |
1796 | (usually slot 0) whereas | |
1797 | ||
1798 | leftcert=%smartcard4:50 | |
1799 | ||
1800 | will directly check slot 4 (which is usually the first slot on the second | |
1801 | reader/token when using the OpenSC library) for a key with ID 0x50. | |
1802 | ||
1803 | ||
1804 | 8.2 Entering the PIN code | |
1805 | --------------------- | |
1806 | ||
1807 | Since the smartcard signing operation needed to sign the hash with the | |
1808 | RSA private key during IKE Main Mode is protected by a PIN code, | |
1809 | the secret PIN must be made available to Pluto. | |
1810 | ||
1811 | For gateways that must be able to start IPsec tunnels automatically in | |
1812 | unattended mode after a reboot, the secret PIN can be stored statically | |
1813 | in ipsec.secrets | |
1814 | ||
1815 | : PIN %smartcard "12345678" | |
1816 | ||
1817 | or with the general notation | |
1818 | ||
1819 | : PIN %smartcard#<n> "<PIN code>" | |
1820 | ||
1821 | or alternatively | |
1822 | ||
1823 | : PIN %smartcard<optional slot nr>:<key id> "<PIN code>" | |
1824 | ||
1825 | On personal notebooks that could get stolen, you wouldn't want to store | |
1826 | your PIN in ipsec.secrets. Thus the alternative form | |
1827 | ||
1828 | : PIN %smartcard %prompt | |
1829 | ||
1830 | will prompt you for the PIN when you start up the first IPsec connection | |
1831 | using the command | |
1832 | ||
1833 | ipsec up sun | |
1834 | ||
1835 | The auto command calls the whack function which in turn communicates with | |
1836 | Pluto over a socket. Since the whack function call is executed from a command | |
1837 | window, Pluto can prompt you for the PIN over this socket connection. | |
1838 | Unfortunately roadwarrior connections which just wait passively for peers | |
1839 | cannot be initiated via the command window: | |
1840 | ||
1841 | conn rw | |
1842 | right=%any | |
1843 | left=%defaultroute | |
1844 | leftcert=%smartcard4:50 | |
1845 | auto=add | |
1846 | ||
1847 | But if there is a corresponding entry | |
1848 | ||
1849 | : PIN %smartcard4:50 %prompt | |
1850 | ||
1851 | in ipsec.secrets, then the standard command | |
1852 | ||
1853 | ipsec rereadsecrets | |
1854 | ||
1855 | or the alias | |
1856 | ||
1857 | ipsec secrets | |
1858 | ||
1859 | can be used to enter the PIN code for this connection interactively. | |
1860 | ||
1861 | The command | |
1862 | ||
1863 | ipsec listcards | |
1864 | ||
1865 | can be executed at any time to check the current status of the PIN code[s]. | |
1866 | ||
1867 | ||
1868 | 8.3 PIN-pad equipped smartcard readers | |
1869 | ---------------------------------- | |
1870 | ||
1871 | Smartcard readers with an integrated PIN-pad offer an increased security | |
1872 | level because the PIN entry cannot be sniffed on the host computer e.g. | |
1873 | by a surrepticiously installed key logger. In order to tell pluto not to | |
1874 | prompt for the PIN on the host itself, the entry | |
1875 | ||
1876 | : PIN %smartcard:50 %pinpad | |
1877 | ||
1878 | can be used in ipsec.secrets. Because the key pad does not cache the PIN in | |
1879 | the smartcard reader, it must be entered for every PKCS #11 session login. | |
1880 | By default pluto does a session logout after every RSA signature. In order | |
1881 | to avoid the repeated entry of the PIN code during the periodic IKE main | |
1882 | mode rekeyings, the following parameter can be set in the config setup | |
1883 | section of ipsec.conf: | |
1884 | ||
1885 | config setup | |
1886 | pkcs11keepstate=yes | |
1887 | ||
1888 | The default setting is pkcs11keepstate=no. | |
1889 | ||
1890 | ||
1891 | 8.4 Configuring a smartcard with pkcsc15-init | |
1892 | ----------------------------------------- | |
1893 | ||
1894 | strongSwan's smartcard solution is based on the PKCS#15 "Cryptographic Token | |
1895 | Information Format Standard" fully supported by OpenSC library functions. | |
1896 | Using the command | |
1897 | ||
1898 | pkcs15-init --erase-card --create-pkcs15 | |
1899 | ||
1900 | a fresh PKCS#15 file structure is created on a smartcard or cryptotoken. | |
1901 | With the next command | |
1902 | ||
1903 | pkcs15-init --auth-id 1 --store-pin --pin "12345678" --puk "87654321" | |
1904 | --label "my PIN" | |
1905 | ||
1906 | a secret PIN code with auth-id 1 is stored in an unretrievable location on | |
1907 | the smart card. The PIN will protect the RSA signing operation. If the PIN | |
1908 | is entered incorrectly more than three times the smartcard will be locked | |
1909 | and the PUK code can be used to unlock the card again. | |
1910 | ||
1911 | Next the RSA private key is transferred to the smartcard | |
1912 | ||
1913 | pkcs15-init --auth-id 1 --store-private-key myKey.pem [--id 45] | |
1914 | ||
1915 | By default the PKCS#15 smartcard record will be assigned the id 45. | |
1916 | Using the --id option multiple key records can be stored on a smartcard. | |
1917 | ||
1918 | At last we load the matching X.509 certificate onto the smartcard | |
1919 | ||
1920 | pkcs15-init --auth-id 1 --store-certificate myCert.pem [--id 45] | |
1921 | ||
1922 | The pkcs15-tool can now be used to verify the contents of the smartcard. | |
1923 | ||
1924 | pkcs15-tool --list-pins --list-keys --list-certificates | |
1925 | ||
1926 | If everything is ok then you are ready to use the generated PKCS#15 | |
1927 | structure with strongSwan. | |
1928 | ||
1929 | 8.5 PKCS#11 proxy functions | |
1930 | ----------------------- | |
1931 | ||
1932 | With the setting pkcs11keepstate=yes some PKCS#11 implementations | |
1933 | (e.g. OpenSC) will lock the access to the smartcard as soon as pluto has | |
1934 | opened a session and will thus prevent other application from sharing the | |
1935 | smartcard resource. In order to solve this locking problem, strongSwan | |
1936 | offers a PKCS#11 proxy service making use of the whack socket communication | |
1937 | channel. The setting | |
1938 | ||
1939 | config setup | |
1940 | pkcs11proxy=yes | |
1941 | ||
1942 | will enable the proxy mode that is disabled by default. | |
1943 | ||
1944 | Currently two smartcard operations are supported: RSA encryption and | |
1945 | RSA decryption. The notation is as follows: | |
1946 | ||
1947 | ipsec scdecrypt <encrypted data> | |
1948 | [--inbase 16|hex|64|base64|256|text|ascii] | |
1949 | [--outbase 16|hex|64|base64|256|text|ascii] | |
1950 | [--keyid <id>] | |
1951 | ||
1952 | The default settings for inbase and outbase is hexadecimal. | |
1953 | Thus the simplest call has the form | |
1954 | ||
1955 | ipsec scdecrypt bb952b71920094ce0696ef9b8b26...12e6 | |
1956 | ||
1957 | and the returned result might be a decrypted 128 bit AES key | |
1958 | ||
1959 | 000 8836362e030e6707c32ffaa0bdad5540 | |
1960 | ||
1961 | The leading three characters represent the return code of the whack channel | |
1962 | with 000 signifying that no error has occured. Here is another example showing | |
1963 | the use of the inbase and outbase attributes | |
1964 | ||
1965 | ipsec scdecrypt m/ewDnTs0k...woE= --inbase base64 --outbase text | |
1966 | ||
1967 | where the result has the form | |
1968 | ||
1969 | 000 This is a secret | |
1970 | ||
1971 | By default the first RSA private key found by the PKCS#11 enumeration is | |
1972 | used. If a different key should be selected then the notation introduced | |
1973 | in sections 8.1 and 8.2 can be used: | |
1974 | ||
1975 | --keyid %smartcard:50 | |
1976 | --keyid %smartcard4:50 | |
1977 | --keyid %smartcard#3 | |
1978 | ||
1979 | with --keyid %smartcard#1 being the default. If supported by the smartcard | |
1980 | and PKCS#11 library RSA encryption can be used with the notation | |
1981 | ||
1982 | ipsec scencrypt <plaintext data> | |
1983 | [--inbase 16|hex|64|base64|256|text|ascii] | |
1984 | [--outbase 16|hex|64|base64|256|text|ascii] | |
1985 | [--keyid <id>] | |
1986 | ||
1987 | with the example | |
1988 | ||
1989 | ipsec scencrypt "This is a secret" --inbase ascii --outbase 64 | |
1990 | ||
1991 | returning the expected output | |
1992 | ||
1993 | 000 m/ewDnTs0k...woE= | |
1994 | ||
1995 | ||
1996 | 9. Configuring the clients | |
1997 | ----------------------- | |
1998 | ||
1999 | 9.1 strongSwan | |
2000 | ---------- | |
2001 | ||
2002 | A strongSwan to strongSwan connection is symmetrical. Any of the four defined | |
2003 | ID types can be used, even different types on either end of the connection, | |
2004 | although this wouldn't make much sense. | |
2005 | ||
2006 | +--------------------------------------------------------------+ | |
2007 | | Connection Definition ID type subjectAltName | | |
2008 | |--------------------------------------------------------------| | |
2009 | | rightid (strongSwan) DER_ASN1_DN - | | |
2010 | | FQDN DNS: | | |
2011 | | USER_FQDN email: | | |
2012 | | IPV4_ADDR IP: | | |
2013 | |--------------------------------------------------------------| | |
2014 | | leftid (strongSwan) DER_ASN1_DN - | | |
2015 | | FQDN DNS: | | |
2016 | | USER_FQDN email: | | |
2017 | | IPV4_ADDR IP: | | |
2018 | +--------------------------------------------------------------+ | |
2019 | ||
2020 | ||
2021 | 9.2 PGPnet | |
2022 | ------ | |
2023 | ||
2024 | Use the file peerCert.p12 to import PGPnet's X.509 certificate, the CA | |
2025 | certificate, plus the encrypted private key in binary PKCS#12 format into the | |
2026 | PGPkey tool. You will be prompted for the passphrase securing the private key. | |
2027 | ||
2028 | Use the file myCert.pem to import the X.509 certificate of the strongSwan | |
2029 | security gateway into the PGPkey tool. The PGPkeyTool does not accept X.509 | |
2030 | certificates in binary DER format, so it must be imported in base64 format: | |
2031 | ||
2032 | -----BEGIN CERTIFICATE----- | |
2033 | M... | |
2034 | ||
2035 | ... | |
2036 | -----END CERTIFICATE----- | |
2037 | ||
2038 | Make sure that there is no human-readable listing of the X.509 certificate in | |
2039 | front of the line | |
2040 | ||
2041 | -----BEGIN CERTIFICATE----- | |
2042 | ||
2043 | otherwise PGPnet will refuse to load the *.PEM file. Any surplus lines can | |
2044 | either be deleted by loading the certificate into a text editor or you can | |
2045 | apply the command | |
2046 | ||
2047 | openssl x509 -in myCert.pem -out myCert.pem | |
2048 | ||
2049 | to achieve the same effect. | |
2050 | ||
2051 | With authentication based on X.509 certificates, PGPnet always sends the ID | |
2052 | type DER_ASN1_DN, therefore rightid in the connection definition of the | |
2053 | strongSwan security gateway must be an ASN.1 distinguished name. | |
2054 | ||
2055 | In the receiving direction PGPnet accepts all four ID types from strongSwan. | |
2056 | ||
2057 | +--------------------------------------------------------------+ | |
2058 | | Connection Definition ID type subjectAltName | | |
2059 | |--------------------------------------------------------------| | |
2060 | | rightid (PGPnet) DER_ASN1_DN - | | |
2061 | |--------------------------------------------------------------| | |
2062 | | leftid (strongSwan) DER_ASN1_DN - | | |
2063 | | FQDN DNS: | | |
2064 | | USER_FQDN email: | | |
2065 | | IPV4_ADDR IP: | | |
2066 | +--------------------------------------------------------------+ | |
2067 | ||
2068 | ||
2069 | 9.3 SafeNet/Soft-PK/Soft-Remote | |
2070 | --------------------------- | |
2071 | ||
2072 | SafeNet/Soft-PK and SafeNet/Soft-Remote can be configured to send their | |
2073 | identity either as DER_ASN1_DN, IPV4_ADDR, FQDN, or USER_FQDN. | |
2074 | In the receiving direction SafeNet/Soft-PK and SafeNet/Soft-Remote | |
2075 | accept all four ID types coming from strongSwan. | |
2076 | ||
2077 | +--------------------------------------------------------------+ | |
2078 | | Connection Definition ID type subjectAltName | | |
2079 | |--------------------------------------------------------------| | |
2080 | | rightid (SafeNet/Soft-PK) DER_ASN1_DN - | | |
2081 | | FQDN DNS: | | |
2082 | | USER_FQDN email: | | |
2083 | | IPV4_ADDR IP: | | |
2084 | |--------------------------------------------------------------| | |
2085 | | leftid (strongSwan) DER_ASN1_DN - | | |
2086 | | FQDN DNS: | | |
2087 | | USER_FQDN email: | | |
2088 | | IPV4_ADDR IP: | | |
2089 | +--------------------------------------------------------------+ | |
2090 | ||
2091 | ||
2092 | 9.4 SSH Sentinel | |
2093 | ------------ | |
2094 | ||
2095 | SSH Sentinel sends its identity as DER_ASN1_DN if the subjectAltName field of | |
2096 | its certificate is empty. If a subjectAltName field is present, then the | |
2097 | corresponding type IPV4_ADDR, FQDN, or USER_FQDN is automatically chosen. | |
2098 | With several subjectAltName entries, the precedence of the different ID types | |
2099 | is not quite clear. In the receiving direction SSH Sentinel accepts all four | |
2100 | ID types from strongSwan. | |
2101 | ||
2102 | +--------------------------------------------------------------+ | |
2103 | | Connection Definition ID type subjectAltName | | |
2104 | |--------------------------------------------------------------| | |
2105 | | rightid (SSH Sentinel) DER_ASN1_DN - | | |
2106 | | FQDN DNS: | | |
2107 | | USER_FQDN email: | | |
2108 | | IPV4_ADDR IP: | | |
2109 | |--------------------------------------------------------------| | |
2110 | | leftid (strongSwan) DER_ASN1_DN - | | |
2111 | | FQDN DNS: | | |
2112 | | USER_FQDN email: | | |
2113 | | IPV4_ADDR IP: | | |
2114 | +--------------------------------------------------------------+ | |
2115 | ||
2116 | ||
2117 | 9.5 Windows 2000/XP | |
2118 | --------------- | |
2119 | ||
2120 | Windows 2000 and Windows XP always send the ID type DER_ASN1_DN, | |
2121 | therefore rightid in the connection definition of the strongSwan | |
2122 | security gateway must be an ASN.1 distinguished name.In the | |
2123 | receiving direction Windows 2000/XP accepts all four ID types | |
2124 | from strongSwan. | |
2125 | ||
2126 | +--------------------------------------------------------------+ | |
2127 | | Connection Definition ID type subjectAltName | | |
2128 | |--------------------------------------------------------------| | |
2129 | | rightid (Windows 2000/XP) DER_ASN1_DN - | | |
2130 | |--------------------------------------------------------------| | |
2131 | | leftid (strongSwan) DER_ASN1_D - | | |
2132 | | FQDN DNS: | | |
2133 | | USER_FQDN email: | | |
2134 | | IPV4_ADDR IP: | | |
2135 | +--------------------------------------------------------------+ | |
2136 | ||
2137 | ||
2138 | 10. Monitoring functions | |
2139 | -------------------- | |
2140 | ||
2141 | strongSwan offers the following monitoring functions: | |
2142 | ||
2143 | ||
2144 | ipsec listalgs | |
2145 | ||
2146 | lists all IKE and ESP cryptographic algorithms that are currently | |
2147 | registered with strongSwan. | |
2148 | ||
2149 | The a listing has the following form: | |
2150 | ||
2151 | List of registered IKE Encryption Algorithms: | |
2152 | ||
2153 | #3 OAKLEY_BLOWFISH_CBC, blocksize: 64, keylen: 128-128-256 | |
2154 | #5 OAKLEY_3DES_CBC, blocksize: 64, keylen: 192-192-192 | |
2155 | #7 OAKLEY_AES_CBC, blocksize: 128, keylen: 128-128-256 | |
2156 | #65004 OAKLEY_SERPENT_CBC, blocksize: 128, keylen: 128-128-256 | |
2157 | #65005 OAKLEY_TWOFISH_CBC, blocksize: 128, keylen: 128-128-256 | |
2158 | #65289 OAKLEY_TWOFISH_CBC_SSH, blocksize: 128, keylen: 128-128-256 | |
2159 | ||
2160 | List of registered IKE Hash Algorithms: | |
2161 | ||
2162 | #1 OAKLEY_MD5, hashsize: 128 | |
2163 | #2 OAKLEY_SHA, hashsize: 160 | |
2164 | #4 OAKLEY_SHA2_256, hashsize: 256 | |
2165 | #6 OAKLEY_SHA2_512, hashsize: 512 | |
2166 | ||
2167 | List of registered IKE DH Groups: | |
2168 | ||
2169 | #2 OAKLEY_GROUP_MODP1024, groupsize: 1024 | |
2170 | #5 OAKLEY_GROUP_MODP1536, groupsize: 1536 | |
2171 | #14 OAKLEY_GROUP_MODP2048, groupsize: 2048 | |
2172 | #15 OAKLEY_GROUP_MODP3072, groupsize: 3072 | |
2173 | #16 OAKLEY_GROUP_MODP4096, groupsize: 4096 | |
2174 | #17 OAKLEY_GROUP_MODP6144, groupsize: 6144 | |
2175 | #18 OAKLEY_GROUP_MODP8192, groupsize: 8192 | |
2176 | ||
2177 | List of registered ESP Encryption Algorithms: | |
2178 | ||
2179 | #3 ESP_3DES, blocksize: 64, keylen: 168-168 | |
2180 | #7 ESP_BLOWFISH, blocksize: 64, keylen: 96-128 | |
2181 | #12 ESP_AES, blocksize: 128, keylen: 128-256 | |
2182 | #252 ESP_SERPENT, blocksize: 128, keylen: 128-256 | |
2183 | #253 ESP_TWOFISH, blocksize: 128, keylen: 128-256 | |
2184 | ||
2185 | List of registered ESP Authentication Algorithms: | |
2186 | ||
2187 | #1 AUTH_ALGORITHM_HMAC_MD5, keylen: 128-128 | |
2188 | #2 AUTH_ALGORITHM_HMAC_SHA1, keylen: 160-160 | |
2189 | #5 AUTH_ALGORITHM_HMAC_SHA2_256, keylen: 256-256 | |
2190 | #7 AUTH_ALGORITHM_HMAC_SHA2_512, keylen: 512-512 | |
2191 | ||
2192 | ||
2193 | The command | |
2194 | ||
2195 | ipsec listpubkeys [--utc] | |
2196 | ||
2197 | lists all public keys currently installed in the chained list of public | |
2198 | keys. These keys were statically loaded from ipsec.conf or aquired either | |
2199 | from received certificates or retrieved from secure DNS servers using | |
2200 | opportunistic mode. | |
2201 | ||
2202 | The public key listing has the following form: | |
2203 | ||
2204 | Feb 11 14:40:18 2005, 2048 RSA Key AwEAAa+uL, | |
2205 | until Sep 09 13:17:25 2009 ok | |
2206 | ID_FQDN '@moon.strongswan.org' | |
2207 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2208 | serial: '03' | |
2209 | Feb 11 14:40:18 2005, 2048 RSA Key AwEAAa+uL, | |
2210 | until Sep 09 13:17:25 2009 ok | |
2211 | ID_DER_ASN1_DN 'C=CH, O=Linux strongSwan, CN=moon.strongswan.org' | |
2212 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2213 | serial: '03' | |
2214 | Feb 11 13:36:53 2005, 2048 RSA Key AwEAAbgbh, | |
2215 | until Dec 31 22:43:18 2009 ok | |
2216 | ID_USER_FQDN 'carol@strongswan.org' | |
2217 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2218 | serial: '0a' | |
2219 | ||
2220 | It consists of | |
2221 | ||
2222 | - the date the public key was installed either in local time or UTC (--utc) | |
2223 | - the modulus size of the RSA key in bits | |
2224 | - a keyID consisting of 9 base64 symbols representing the public exponent | |
2225 | and the most significant bits of the modulus | |
2226 | - the expiration date of the public key (extracted from the certificate) | |
2227 | - the type and value of the ID associated with the public key. | |
2228 | - the issuer of the certificate the public key was extracted from. | |
2229 | - the serial number of the certificate the public key was extracted from. | |
2230 | ||
2231 | A public key can be associated with several IDs, e.g. using subjectAltNames | |
2232 | in certificates and an ID can possess several public keys, e.g. retrieved | |
2233 | from a secure DNS server. | |
2234 | ||
2235 | ||
2236 | The command | |
2237 | ||
2238 | ipsec listcerts [--utc] | |
2239 | ||
2240 | lists all local certificates, both strongSwan's own and those of | |
2241 | trusted peer loaded via leftcert and rightcert, respectively. | |
2242 | ||
2243 | The output has the form | |
2244 | ||
2245 | Feb 11 13:36:47 2005, count: 4 | |
2246 | subject: 'C=CH, O=Linux strongSwan, CN=moon.strongswan.org' | |
2247 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2248 | serial: 03 | |
2249 | pubkey: 2048 RSA Key AwEAAa+uL, has private key | |
2250 | validity: not before Sep 10 13:17:25 2004 ok | |
2251 | not after Sep 09 13:17:25 2009 ok | |
2252 | subjkey: e5:e4:10:87:6c:2a:c4:be:ad:85:49:42:a6:de:76:58:30:3a:9f:c1 | |
2253 | authkey: 5d:a7:dd:70:06:51:32:7e:e7:b6:6d:b3:b5:e5:e0:60:ea:2e:4d:ef | |
2254 | aserial: 00 | |
2255 | ||
2256 | and shows | |
2257 | ||
2258 | - the date the certificate was installed either in local time or UTC (--utc) | |
2259 | - the count shows how many connections refer to this certificate | |
2260 | - the subject of the certificate | |
2261 | - the issuer of the certificate | |
2262 | - the serial number of the certificate | |
2263 | - the size and keyid of the RSA public key contained in the certificate. | |
2264 | the label "has private key" indicates that a matching RSA private key | |
2265 | has been found, defined or loaded in ipsec.secrets. | |
2266 | - the label "on smartcard" indicates that the certificate was loaded from | |
2267 | a smartcard or cryptotoken and that most probably a matching RSA private | |
2268 | key also resides on-card. | |
2269 | - the validity of the CA certificate expressed either in local time or | |
2270 | UTC (--utc). The validity is checked automatically resulting either | |
2271 | in an "ok" message or a "fatal" error message. | |
2272 | - the optional subjectKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2273 | over the certificate's public key. | |
2274 | - the optional authorityKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2275 | over the public key of the issuer who signed the certificate. | |
2276 | - the serial number of the issuer's certificate. | |
2277 | ||
2278 | ||
2279 | The command | |
2280 | ||
2281 | ipsec listcacerts [--utc] | |
2282 | ||
2283 | lists all CA certificates that have been either been loaded from the directory | |
2284 | /etc/ipsec.d/cacerts/ or received via the IKE protocol. The output has the form | |
2285 | ||
2286 | Feb 11 13:36:52 2005, count: 1 | |
2287 | subject: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2288 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2289 | serial: 00 | |
2290 | pubkey: 2048 RSA Key AwEAAb/yX | |
2291 | validity: not before Sep 10 13:01:45 2004 ok | |
2292 | not after Sep 08 13:01:45 2014 ok | |
2293 | subjkey: 5d:a7:dd:70:06:51:32:7e:e7:b6:6d:b3:b5:e5:e0:60:ea:2e:4d:ef | |
2294 | authkey: 5d:a7:dd:70:06:51:32:7e:e7:b6:6d:b3:b5:e5:e0:60:ea:2e:4d:ef | |
2295 | aserial: 00 | |
2296 | ||
2297 | and shows | |
2298 | ||
2299 | - the date the CA certificate was installed either in local time or UTC (--utc) | |
2300 | - the count is always set to 1 | |
2301 | - the subject of the CA certificate | |
2302 | - the issuer of the CA certificate | |
2303 | - the serial number of the CA certificate | |
2304 | - the size and keyid of the RSA public key contained in the certificate. | |
2305 | - the validity of the CA certificate expressed either in local time or | |
2306 | UTC (--utc). The validity is checked automatically resulting either | |
2307 | in an "ok" message or a "fatal" error message. | |
2308 | - the optional subjectKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2309 | over the CA certificate's public key. | |
2310 | - the optional authorityKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2311 | over the public key of the issuer who signed the CA certificate. | |
2312 | For Root CA certificates the authorityKeyIdentifier and subjectKeyIdentifier | |
2313 | fields must be equal. | |
2314 | - the serial number of the issuer's certificate. | |
2315 | ||
2316 | ||
2317 | The command | |
2318 | ||
2319 | ipsec listaacerts [--utc] | |
2320 | ||
2321 | lists all Authorization Authority certificates that have been loaded from | |
2322 | the directory /etc/ipsec.d/aacerts/. | |
2323 | The output has the form | |
2324 | ||
2325 | Dec 20 13:29:55 2004, count: 1 | |
2326 | subject: 'C=CH, O=strongSec GmbH, CN=strongSec Authorization Authority' | |
2327 | issuer: 'C=CH, O=strongSec GmbH, CN=strongSec Root CA' | |
2328 | serial: 0f | |
2329 | pubkey: 2048 RSA Key AwEAAfazH | |
2330 | validity: not before Aug 24 13:41:56 2003 ok | |
2331 | not after Aug 23 13:41:56 2005 ok | |
2332 | subjkey: 56:89:b9:28:c9:1b:a0:00:7f:50:9d:ec:28:75:23:c1:1e:d1:dd:90 | |
2333 | authkey: af:80:d5:c6:02:1c:96:78:b3:85:a5:65:a2:23:fd:ad:cf:e2:55:b2 | |
2334 | aserial: 00 | |
2335 | ||
2336 | and shows | |
2337 | ||
2338 | - the date the AA certificate was installed either in local time or UTC (--utc) | |
2339 | - the count is always set to 1 | |
2340 | - the subject of the AA certificate | |
2341 | - the issuer of the AA certificate | |
2342 | - the serial number of the AA certificate | |
2343 | - the size and keyid of the RSA public key contained in the certificate. | |
2344 | - the validity of the AA certificate expressed either in local time or | |
2345 | UTC (--utc). The validity is checked automatically resulting either | |
2346 | in an "ok" message or a "fatal" error message. | |
2347 | - the optional subjectKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2348 | over the AA certificate's public key. | |
2349 | - the optional authorityKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2350 | over the public key of the issuer who signed the AA certificate. | |
2351 | - the serial number of the issuer's certificate. | |
2352 | ||
2353 | ||
2354 | The command | |
2355 | ||
2356 | ipsec listocspcerts [--utc] | |
2357 | ||
2358 | lists all OCSO signer certificates that have been either loaded from | |
2359 | /etc/ipsec.d/ocspcerts/ or have been received included in the OCSP server | |
2360 | response. The output has the form | |
2361 | ||
2362 | Feb 09 22:56:17 2005, count: 1 | |
2363 | subject: 'C=CH, O=Linux strongSwan, OU=OCSP, CN=ocsp.strongswan.org' | |
2364 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2365 | serial: 09 | |
2366 | pubkey: 2048 RSA Key AwEAAaonT | |
2367 | validity: not before Nov 19 17:29:28 2004 ok | |
2368 | not after Nov 18 17:29:28 2009 ok | |
2369 | subjkey: 88:07:0a:b8:ae:c7:c1:07:5c:be:68:6a:c4:a5:7f:81:1f:37:b5:56 | |
2370 | authkey: 5d:a7:dd:70:06:51:32:7e:e7:b6:6d:b3:b5:e5:e0:60:ea:2e:4d:ef | |
2371 | aserial: 00 | |
2372 | ||
2373 | and shows | |
2374 | ||
2375 | - the date the OCSP signer certificate was installed either in local time | |
2376 | or UTC (--utc) | |
2377 | - the count is always set to 1 | |
2378 | - the subject of the OCSP signer certificate | |
2379 | - the issuer of the OCSP signer certificate | |
2380 | - the serial number of the OCSP signer certificate | |
2381 | - the size and keyid of the RSA public key contained in the certificate. | |
2382 | - the validity of the OCSP signer certificate expressed either in local time | |
2383 | or UTC (--utc). The validity is checked automatically resulting either | |
2384 | in an "ok" message or a "fatal" error message. | |
2385 | - the optional subjectKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2386 | over the OCSP signer certificate's public key. | |
2387 | - the optional authorityKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2388 | over the public key of the issuer who signed the OCSP certificate. | |
2389 | - the serial number of the issuer's certificate. | |
2390 | ||
2391 | ||
2392 | The command | |
2393 | ||
2394 | ipsec listacerts [--utc] | |
2395 | ||
2396 | lists all X.509 attribute certificates that have been loaded from the directory | |
2397 | /etc/ipsec.d/acerts/. | |
2398 | The output has the form | |
2399 | ||
2400 | Dec 20 13:29:56 2004 | |
2401 | holder: 'C=CH, O=strongSec GmbH, CN=Andreas Steffen' | |
2402 | hissuer: 'C=CH, O=strongSec GmbH, CN=strongSec Root CA' | |
2403 | hserial: 1e | |
2404 | groups: Research, Sales | |
2405 | issuer: 'C=CH, O=strongSec GmbH, CN=strongSec Authorization Authority' | |
2406 | serial: 2c | |
2407 | validity: not before Dec 19 14:51:38 2004 ok | |
2408 | not after Dec 20 14:51:38 2004 fatal (expired) | |
2409 | authkey: 56:89:b9:28:c9:1b:a0:00:7f:50:9d:ec:28:75:23:c1:1e:d1:dd:90 | |
2410 | aserial: 0f | |
2411 | ||
2412 | and shows | |
2413 | ||
2414 | - the date the attribute certificate was installed either in local time | |
2415 | or UTC (--utc) | |
2416 | - the holder of the attribute certificate | |
2417 | - the issuer of holder's certificate | |
2418 | - the serial number of the holder's certificate | |
2419 | - the group attributes | |
2420 | - the issuing Authorization Authority of the attribute certificate | |
2421 | - the serial number of the attribute certificate | |
2422 | - the validity of the attribute certificate expressed either in local time or | |
2423 | UTC (--utc). The validity is checked automatically resulting either | |
2424 | in an "ok" message or a "fatal" error message. | |
2425 | - an authorityKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2426 | over the public key of the issuing Authorization Authority | |
2427 | - the serial number of the AA certificate. | |
2428 | ||
2429 | ||
2430 | The command | |
2431 | ||
2432 | ipsec listgroups [--utc] | |
2433 | ||
2434 | lists all group attributes either defined in right|leftgroups statements | |
2435 | in ipsec.conf or contained in loaded X.509 attribute certificates. | |
2436 | The output has the form | |
2437 | ||
2438 | Dec 20 13:29:55 2004, count: 4 | |
2439 | Research | |
2440 | Dec 20 13:30:04 2004, count: 1 | |
2441 | Research New York | |
2442 | Dec 20 13:29:55 2004, count: 3 | |
2443 | Sales | |
2444 | ||
2445 | and shows | |
2446 | ||
2447 | - the date the group attribute was first installed either in local time | |
2448 | or UTC (--utc) | |
2449 | - the count shows how many times the attribute is used | |
2450 | - the group name | |
2451 | ||
2452 | ||
2453 | The command | |
2454 | ||
2455 | ipsec listcainfos [--utc] | |
2456 | ||
2457 | lists the properties defined by the ca definition sections in ipsec.conf. | |
2458 | The output has the form | |
2459 | ||
2460 | Jun 08 22:31:37 2004, "strongswan" | |
2461 | authname: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2462 | ldaphost: 'ldap.strongswan.org' | |
2463 | ocspuri: 'http://ocsp.strongswan.org:8880' | |
2464 | distPts: 'http://crl.strongswan.org/strongswan.crl' | |
2465 | 'ldap:///O=Linux strongSwan, C=CH?certificateRevocationList' | |
2466 | authkey: 5d:a7:dd:70:06:51:32:7e:e7:b6:6d:b3:b5:e5:e0:60:ea:2e:4d:ef | |
2467 | aserial: 00 | |
2468 | ||
2469 | and shows | |
2470 | ||
2471 | - the date the CA definition was loaded either in local time or UTC (--utc) | |
2472 | - the name of the ca section | |
2473 | - the distinguished name of the CA | |
2474 | - an optional default ldap host for the CA | |
2475 | - an optional OCSP URI | |
2476 | - a maximum of two optional CRL distribution points | |
2477 | - the optional authorityKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2478 | over the public key of the CA. | |
2479 | - the serial number of the CA. | |
2480 | ||
2481 | ||
2482 | The command | |
2483 | ||
2484 | ipsec listcrls [--utc] | |
2485 | ||
2486 | lists all CRLs that have been loaded from /etc/ipsec.d/crls/. | |
2487 | The output has the form | |
2488 | ||
2489 | Feb 11 13:37:00 2005, revoked certs: 1 | |
2490 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2491 | distPts: 'http://crl.strongswan.org/strongswan.crl' | |
2492 | updates: this Feb 08 07:46:29 2005 | |
2493 | next Mar 10 07:46:29 2005 ok | |
2494 | authkey: 5d:a7:dd:70:06:51:32:7e:e7:b6:6d:b3:b5:e5:e0:60:ea:2e:4d:ef | |
2495 | aserial: 00 | |
2496 | ||
2497 | and shows | |
2498 | ||
2499 | - the date the CRL was installed either in local time or UTC (--utc) | |
2500 | - the number revoked certificates | |
2501 | - the issuer of the CRL | |
2502 | - the URLs of the distribution points where the CRL can be fetched from. | |
2503 | - the dates when the CRL was issued and when the next update | |
2504 | is expected, respectively, expressed either in local time or | |
2505 | UTC (--utc). It is automatically checked if the next update | |
2506 | deadline has passed, resulting either in an "ok" message, a | |
2507 | a "warning" message when strictcrlpolicy=no or a "fatal" message when | |
2508 | strictcrlpolicy=yes. | |
2509 | - the optional authorityKeyIdentifier extension which is a 20 byte SHA-1 hash | |
2510 | over the public key of the issuer who signed the CRL. This extension is | |
2511 | present in version 2 CRLs, only. | |
2512 | - the serial number of the issuer's certificate. | |
2513 | ||
2514 | ||
2515 | The command | |
2516 | ||
2517 | ||
2518 | ipsec listocsp [--utc] | |
2519 | ||
2520 | lists the contents of the OCSP response cache. The output has the form | |
2521 | ||
2522 | issuer: 'C=CH, O=Linux strongSwan, CN=strongSwan Root CA' | |
2523 | uri: 'http://ocsp.strongswan.org:8880' | |
2524 | authname: 13:9d:a0:9e:f4:32:ab:8f:e2:89:56:67:fa:d0:d4:e3:35:86:71:b9 | |
2525 | authkey: 5d:a7:dd:70:06:51:32:7e:e7:b6:6d:b3:b5:e5:e0:60:ea:2e:4d:ef | |
2526 | aserial: 00 | |
2527 | Feb 09 22:56:17 2005, until Feb 09 23:01:17 2005 warning (expires in 4 minutes) | |
2528 | serial: 0a, good | |
2529 | ||
2530 | and shows | |
2531 | ||
2532 | - the distinguished name of the CA handled by the OCSP server | |
2533 | - the http URI of the OCSP server. | |
2534 | - the 20 byte SHA-1 hash of the CA's distinguished name | |
2535 | - the 20 byte SHA-1 hash of the CA's public key | |
2536 | - the serial number of the CA's certificate | |
2537 | - a certificate status list showing | |
2538 | - the time the OCSP status was received | |
2539 | - an optional nextUpdate deadline (if missing the OCSP status will be | |
2540 | onetime with a lifetime of 2 minutes only). | |
2541 | - the serial number of the certificate | |
2542 | - the status of the certificate (good, revoked, unknown) | |
2543 | ||
2544 | ||
2545 | The command | |
2546 | ||
2547 | ipsec listcards [--utc] | |
2548 | ||
2549 | lists all smartcard records that are currently in use by Pluto. | |
2550 | The output has the form | |
2551 | ||
2552 | Aug 17 16:47:59 2005, #1, count: 6 | |
2553 | slot: 0, session closed, logged out, has valid pin | |
2554 | id: 45 | |
2555 | label: 'strongSwan' | |
2556 | subject: 'C=CH, O=Linux strongSwan, CN=carol@strongswan.org' | |
2557 | ||
2558 | with pkcs11keepstate=no and | |
2559 | ||
2560 | Aug 17 16:47:59 2005, #1, count: 6 | |
2561 | slot: 0, session opened, logged in, has pin pad | |
2562 | id: 45 | |
2563 | label: 'strongSwan' | |
2564 | subject: 'C=CH, O=Linux strongSwan, CN=carol@strongswan.org' | |
2565 | ||
2566 | with pkcs11keepstate=yes and shows | |
2567 | ||
2568 | - the date the certificate was read from the smartcard record | |
2569 | - the certificate objects are numbered starting from #1 | |
2570 | - the count shows how many connections and secret pin entries point | |
2571 | to the smartcard record | |
2572 | - the PKCS #11 slot number | |
2573 | - the PKCS #11 session state: closed | opened | |
2574 | - the PKCS #11 session login state: logged out | logged in | |
2575 | - the status of the PIN: no pin | valid pin | invalid pin | pin pad | |
2576 | - the ID of the certificate object | |
2577 | - the label of the certificate object | |
2578 | - the subject distinguished name of the certificate | |
2579 | ||
2580 | ||
2581 | The command | |
2582 | ||
2583 | ipsec auto --listall [--utc] | |
2584 | ||
2585 | is equivalent to | |
2586 | ||
2587 | ipsec listalgs | |
2588 | ipsec listpubkeys [--utc] | |
2589 | ipsec listcerts [--utc] | |
2590 | ipsec listcacerts [--utc] | |
2591 | ipsec listaacerts [--utc] | |
2592 | ipsec listocspcerts [--utc] | |
2593 | ipsec listacerts [--utc] | |
2594 | ipsec listgroups [--utc] | |
2595 | ipsec listcainfos [--utc] | |
2596 | ipsec listcrls [--utc] | |
2597 | ipsec listocsp [--utc] | |
2598 | ipsec listcards [--utc] | |
2599 | ||
2600 | ||
2601 | 11. Firewall support functions | |
2602 | -------------------------- | |
2603 | ||
2604 | ||
2605 | 11.1 Environment variables in the updown script | |
2606 | ------------------------------------------ | |
2607 | ||
2608 | strongSwan makes the following environment variables available | |
2609 | in the updown script indicated by the leftupdown option: | |
2610 | ||
2611 | +------------------------------------------------------------------+ | |
2612 | | Variable Example Comment | | |
2613 | |------------------------------------------------------------------| | |
2614 | | $PLUTO_PEER_ID carol@strongswan.org USER_FQDN (1) | | |
2615 | |------------------------------------------------------------------| | |
2616 | | $PLUTO_PEER_PROTOCOL 17 udp (2) | | |
2617 | |------------------------------------------------------------------| | |
2618 | | $PLUTO_PEER_PORT 68 bootpc (3) | | |
2619 | |------------------------------------------------------------------| | |
2620 | | $PLUTO_PEER_CA C=CH, O=ACME, CN=Sales CA (4) | | |
2621 | |------------------------------------------------------------------| | |
2622 | | $PLUTO_MY_ID @moon.strongswan.org FQDN (1) | | |
2623 | |------------------------------------------------------------------| | |
2624 | | $PLUTO_MY_PROTOCOL 17 udp (2) | | |
2625 | |------------------------------------------------------------------| | |
2626 | | $PLUTO_MY_PORT 67 bootps (3) | | |
2627 | +------------------------------------------------------------------+ | |
2628 | ||
2629 | (1) $PLUTO_PEER_ID/$PLUTO_MY_ID contain the IDs of the two ends | |
2630 | of an established connection. In our examples these | |
2631 | correspond to the strings defined by rightid and leftid, | |
2632 | respectively. | |
2633 | ||
2634 | (2) $PLUTO_PEER_PROTOCOL/$PLUTO_MY_PROTOCOL contain the protocol | |
2635 | defined by the rightprotoport and leftprotoport options, | |
2636 | respectively. Both variables contain the same protocol value. | |
2637 | The variables take on the value '0' if no protocol has been defined. | |
2638 | ||
2639 | (3) $PLUTO_PEER_PORT/$PLUTO_MY_PORT contain the ports defined by | |
2640 | the rightprotoport and leftprotoport options, respectively. | |
2641 | The variables take on the value '0' if no port has been defined. | |
2642 | ||
2643 | (4) $PLUTO_PEER_CA contains the distinguished name of the CA that | |
2644 | issued the peer's certificate. | |
2645 | ||
2646 | ||
2647 | 11.2 Automatic insertion and deletion of iptables firewall rules | |
2648 | ----------------------------------------------------------- | |
2649 | ||
2650 | Starting with strongswan-2.7.0, the default _updown script automatically inserts | |
2651 | and deletes dynamic iptables firewall rules upon the establishment or teardown, | |
2652 | respectively, of an IPsec security association. This new feature is activated | |
2653 | with the line | |
2654 | ||
2655 | leftfirewall=yes | |
2656 | ||
2657 | and can be used when the following prerequisites are fulfilled: | |
2658 | ||
2659 | - Linux 2.4.x kernel, KLIPS IPsec stack, and arbitrary iptables version. | |
2660 | Filtering of tunneled traffic is based on ipsecN interfaces. | |
2661 | ||
9820c0e2 | 2662 | - Linux 2.6.16 kernel or newer, native NETKEY IPsec stack, and |
997358a6 MW |
2663 | iptables-1.3.5 or newer. Filtering of tunneled traffic is based on |
2664 | IPsec policy matching rules. | |
2665 | ||
2666 | If you define a local client subnet with a netmask larger than /32 behind | |
2667 | the gateway then the automatically inserted FORWARD iptables rules will | |
2668 | not allow to access the internal IP address of the host although it is | |
2669 | part of the client subnet definition. If you want additional INPUT and | |
2670 | OUTPUT iptables rules to be inserted, so that the host itself can be accessed | |
2671 | then add the following line: | |
2672 | ||
2673 | lefthostaccess=yes | |
2674 | ||
2675 | The _updown script also features a logging facility which will register the | |
2676 | creation (+) and the expiration (-) of each successfully established VPN | |
2677 | connection in a special syslog file in the following concise and easily | |
2678 | readable format: | |
2679 | ||
2680 | Jul 19 18:58:38 moon vpn: | |
2681 | + @carol.strongswan.org 192.168.0.100 -- 192.168.0.1 == 10.1.0.0/16 | |
2682 | Jul 19 22:15:17 moon vpn: | |
2683 | - @carol.strongswan.org 192.168.0.100 -- 192.168.0.1 == 10.1.0.0/16 | |
2684 | ||
2685 | ||
2686 | 11.3 Sample Linux 2.6 updown script for iptables < 1.3.5 | |
2687 | --------------------------------------------------- | |
2688 | ||
2689 | If you are using a Linux 2.6 kernel older than 2.6.16 or an iptables version | |
2690 | older than 1.3.5 then the IPsec policy matching rules will not be available. | |
2691 | In order to make sure that only tunneled packets are accepted, a mark can be | |
2692 | set on incoming ESP packets. This "ESP" mark will be retained on the | |
2693 | decapsulated packet so that iptables rules inserted by the updown script can | |
2694 | check on the presence of this mark. For this purpose the template located in | |
2695 | ||
2696 | programs/_updown_espmark | |
2697 | ||
2698 | can be used. Store a copy of _updown_espmark e.g. in /etc/ipsec.updown and load | |
2699 | the script with the line | |
2700 | ||
2701 | leftupdown=/etc/updown.ipsec. | |
2702 | ||
2703 | In addition for the dynamic updown script to work the following static iptables rules | |
2704 | must be applied: | |
2705 | ||
2706 | iptables -t mangle -A INPUT -p 50 -j MARK --set-mark 50 | |
2707 | ||
2708 | ||
2709 | 12. Authentication with raw RSA public keys | |
2710 | --------------------------------------- | |
2711 | ||
2712 | FreeS/WAN, as it is available from www.freeswan.org does public key | |
2713 | authentication with raw RSA public keys that are directly defined in | |
2714 | /etc/ipsec.conf | |
2715 | ||
2716 | rightrsasigkey=0sAq4c.... | |
2717 | ||
2718 | When version 1.x of standard FreeS/WAN receives a certificate request (CR), | |
2719 | it immediately drops the negotiation because it does not know how to answer | |
2720 | the request. As a workaround strongSwan does not send a CR if the RSA | |
2721 | key has been statically loaded using [right/left]rsasigkey. A problem | |
2722 | remains with roadwarriors initiating a connection. Since strongSwan | |
2723 | does not know the identity of the initiating peer in advance, it will always | |
2724 | send a CR, causing the rupture of the IKE negotiation if the peer is a | |
2725 | version 1.x FreeS/WAN host. To circumvent this problem the configuration | |
2726 | parameter 'nocrsend' can be set in the config setup section of /etc/ipsec.conf: | |
2727 | ||
2728 | config setup: | |
2729 | nocrsend=yes | |
2730 | ||
2731 | With this entry no certificate request is sent in any connection. | |
2732 | The default setting is nocrsend=no. | |
2733 | ||
2734 | ||
2735 | 13. Authentication with OpenPGP certificates | |
2736 | ---------------------------------------- | |
2737 | ||
2738 | strongSwan also supports RSA based authentication using OpenPGP | |
2739 | certificates and OpenPGP V3 fingerprints used as an KEY_ID identifier. | |
2740 | ||
2741 | ||
2742 | 13.1 OpenPGP certificates | |
2743 | -------------------- | |
2744 | ||
2745 | OpenPGP certificates containing RSA public keys can now directly be loaded | |
2746 | in ASCII armored PGP format using the leftcert and rightcert parameters | |
2747 | in /etc/ipsec.conf: | |
2748 | ||
2749 | conn pgp | |
2750 | right=%any | |
2751 | righcert=peerCert.asc | |
2752 | left=%defaultroute | |
2753 | leftcert=gatewayCert.asc | |
2754 | ||
2755 | The peer certificate must be stored locally (the default directory is | |
2756 | /etc/ipsec.d/certs) since currently no trust can be established for | |
2757 | PGP certificates received from a peer via the IKE protocol. | |
2758 | ||
2759 | ||
2760 | 13.2 OpenPGP private keys | |
2761 | -------------------- | |
2762 | ||
2763 | PGP private keys in unencrypted form can now directly be loaded in ASCII | |
2764 | armored PGP format via an entry in /etc/ipsec.secrets: | |
2765 | ||
2766 | : RSA gatewayKey.asc | |
2767 | ||
2768 | Existing IDEA-encrypted RSA private keys can be unlocked with GnuPG and | |
2769 | the IDEA extension (see http://www.gnupg.org/gph/en/pgp2x.html) using | |
2770 | the commands | |
2771 | ||
2772 | gpg --import gatewayCert.asc | |
2773 | ||
2774 | gpg --allow-secret-key-import --import gatewayKey.asc | |
2775 | ||
2776 | gpg --edit-key <gateway ID> | |
2777 | > passwd #change to empty password | |
2778 | > save | |
2779 | ||
2780 | gpg -a --export-secret-key <gateway ID> gatewayKey.asc | |
2781 | ||
2782 | ||
2783 | 13.3 Monitoring functions | |
2784 | -------------------- | |
2785 | ||
2786 | The command ipsec listcerts shows all loaded PGP certificates | |
2787 | in the following format: | |
2788 | ||
2789 | Aug 28 09:51:55 2002, count: 1 | |
2790 | fingerprint: 0x1ccfca12d93467ffa9d5093d87a465dc | |
2791 | pubkey: 1024 RSA Key ARHso6uKQ | |
2792 | created: Aug 27 08:51:39 2002 | |
2793 | until: --- -- --:--:-- ---- ok (expires never) | |
2794 | ||
2795 | The entries are | |
2796 | ||
2797 | - the date the certificate was loaded either in local time or UTC (--utc) | |
2798 | - the V3 fingerprint consisting of the 16 byte MD5 hash of the public key | |
2799 | which is used as an ID of type KEY_ID | |
2800 | - the modulus size of the RSA key in bits | |
2801 | - a keyID consisting of 9 base64 symbols representing the public exponent | |
2802 | and the most significant bits of the modulus | |
2803 | - the creation date of the public key (extracted from the certificate) | |
2804 | - the optional expiration date of the public key (extracted from the | |
2805 | certificate) | |
2806 | ||
2807 | ||
2808 | 13.4 Suppression of certificate request messages | |
2809 | ------------------------------------------- | |
2810 | ||
2811 | PGPnet configured to work with OpenPGP certificates aborts the IKE | |
2812 | negotiation when it receives a X.509 certificate. Therefore it is recommended | |
2813 | (mandatory for roadwarrior connections) to set | |
2814 | ||
2815 | config setup: | |
2816 | nocrsend=yes | |
2817 | ||
2818 | in /etc/ipsec.conf. | |
2819 | ||
2820 | ||
2821 | 14. Additional Features | |
2822 | ------------------- | |
2823 | ||
2824 | ||
2825 | 14.1 Authentication and encryption algorithms | |
2826 | ---------------------------------------- | |
2827 | ||
2828 | strongSwan supports the following suite of encryption and authentication | |
2829 | algorithms for both IKE and ESP payloads. | |
2830 | ||
2831 | +------------------------------------------------------------------+ | |
2832 | | IKE algorithms (negotiated in Phase 1 Main Mode) | | |
2833 | +------------------------------------------------------------------+ | |
2834 | | Encryption algorithms: 3des, aes, serpent, twofish, blowfish | | |
2835 | |------------------------------------------------------------------| | |
2836 | | Hash algorithms: md5, sha, sha2 | | |
2837 | |------------------------------------------------------------------| | |
2838 | | DH groups: 1024, 1536, 2048, 3072, 4096, 6144, 8192 | | |
2839 | +------------------------------------------------------------------+ | |
2840 | ||
2841 | NOTE: For IKE the SHA-1 algorithm is denoted by "sha" | |
2842 | ||
2843 | The cryptographic IKE algorithms listed above are a fixed part of the | |
2844 | strongSwan distribution. Particular algorithms can be added or removed | |
2845 | in the "programs/pluto/alg" directory. | |
2846 | ||
2847 | +------------------------------------------------------------------+ | |
2848 | | ESP algorithms (negotiated in Phase 2 Quick Mode) | | |
2849 | +------------------------------------------------------------------+ | |
2850 | | Encryption algorithms: 3des, aes, serpent, twofish, blowfish | | |
2851 | |------------------------------------------------------------------| | |
2852 | | Hash algorithms: md5, sha1, sha2 | | |
2853 | |------------------------------------------------------------------| | |
2854 | | PFS groups: 1024, 1536, 2048, 3072, 4096, 6144, 8192 | | |
2855 | +------------------------------------------------------------------+ | |
2856 | ||
2857 | The cryptographic ESP algorithms listed above are a fixed part of the | |
2858 | strongSwan distribution. If your Linux 2.4 or 2.6 kernel includes the | |
2859 | CryptoAPI then additional ESP algorithms can be added or deleted as | |
2860 | kernel modules. | |
2861 | ||
2862 | The IKE and ESP cryptographic algorithms to be proposed to the peer | |
2863 | as an initiator can be specified on a per connection basis in the form | |
2864 | ||
2865 | conn normal | |
2866 | ... | |
2867 | ike=aes128-sha-modp1536,3des-sha-modp1536 | |
2868 | esp=aes128-sha1,3des-sha1 | |
2869 | ... | |
2870 | ||
2871 | or if you are more paranoid | |
2872 | ||
2873 | conn paranoid | |
2874 | ... | |
2875 | ike=aes256-sha2_512-modp2048 | |
2876 | esp=aes256-sha2_512 | |
2877 | ... | |
2878 | ||
2879 | If the the "ike" and "esp" configuration parameters are missing in | |
2880 | ipsec.conf, then the default settings | |
2881 | ||
2882 | ike=3des-md5-modp1536,3des-sha-modp1536,\ | |
2883 | 3des-md5-modp1024,3des-sha-modp1024 | |
2884 | esp=3des-md5,3des-sha1 | |
2885 | ||
2886 | arre implicitly assumed. The 3DES encryption algorithm and the MD5 and | |
2887 | SHA-1 hash algorithms are hardcoded into strongSwan and cannot be removed. | |
2888 | ||
2889 | If Perfect Forward Secrecy (PFS is desired), then a PFS group can be | |
2890 | optionally specified: | |
2891 | ||
2892 | conn make_sure | |
2893 | ... | |
2894 | pfs=yes | |
2895 | pfsgroup=modp2048,modp1536 | |
2896 | ... | |
2897 | ||
2898 | If the "pfs" parameter is missing then "pfs=yes" is assumed by default. | |
2899 | This means that PFS must be disabled explicitly by setting "pfs=no". | |
2900 | ||
2901 | If the "pfsgroup" parameter is missing then the default is | |
2902 | ||
2903 | pfsgroup=<Phase1 DH group> | |
2904 | ||
2905 | The "ike" and "esp" parameters are used to formulate one or several | |
2906 | transform proposals to the peer if the strongSwan VPN host is the initiator. | |
2907 | Attention! As a responder the first proposal from the peer is accepted that | |
2908 | is supported the by one of the registered algorithms listed by the command | |
2909 | ||
2910 | ipsec listalgs | |
2911 | ||
2912 | If the responder wants to restrict the allowed cipher suites the '!' flag | |
2913 | can be used to do so. The configuration | |
2914 | ||
2915 | conn normal_but_strict | |
2916 | ... | |
2917 | ike=aes128-sha-modp1536,3des-sha-modp1536! | |
2918 | esp=aes128-sha1,3des-sha1! | |
2919 | ... | |
2920 | ||
2921 | will only permit the listed algorithms defined above but no other methods | |
2922 | even if they might be supported by the responder. | |
2923 | ||
2924 | ||
2925 | 14.2 NAT traversal | |
2926 | ------------- | |
2927 | ||
2928 | Currently please refer to README.NAT-Traversal document in the strongSwan | |
2929 | distribution. | |
280f5aeb AS |
2930 | |
2931 | ||
997358a6 MW |
2932 | 14.3 Dead peer detection |
2933 | -------------------- | |
2934 | ||
2935 | strongSwan implements the RFC 3706 Dead Peer Detection (DPD) keep-alive | |
2936 | scheme. If an established IPsec SA has been idle (i.e. without any traffic) | |
2937 | for N seconds (dpddelay=N) then strongSwan side sends a "hello" message | |
2938 | (R_U_THERE) and the peer replies with an acknowledge message (R_U_THERE_ACK). | |
2939 | If no response is received, the R_U_THERE messages are repeated until a DPD | |
2940 | timeout of M seconds (dpdtimeout=M) has elapsed. If still no traffic or | |
2941 | R_U_THERE_ACK packets were received, the peer is declared to be dead and all | |
2942 | SAs belonging to a common Phase 1 SA are deleted. | |
2943 | ||
2944 | DPD support is tuneable on a per connection basis by using the dpdaction, | |
2945 | dpddelay and dpdtimeout directives: | |
2946 | ||
2947 | conn roadwarrior | |
2948 | right=%any | |
2949 | left=%defaultroute | |
2950 | leftsubnet=10.1.0.0/16 | |
2951 | dpdaction=clear | |
2952 | ||
2953 | conn net-to-net | |
2954 | right=192.168.0.2 | |
2955 | rightsubnet=10.2.0.0/16 | |
2956 | left=%defaultroute | |
2957 | leftsubnet=10.1.0.0/16 | |
2958 | dpdaction=hold | |
2959 | dpddelay=60 | |
2960 | dpdtimeout=500 | |
2961 | ||
2962 | In the first example dpdaction=clear activates the DPD mechanism under the | |
2963 | condition that the peer supports RFC 3706. The values dpddelay=30s and | |
2964 | dpdtimeout=120s are assumed by default in the absence of these parameters, so | |
2965 | that during idle periods an R_U_THERE packet is sent every 30 seconds. If no | |
2966 | traffic or a no R_U_THERE_ACK packet is received from the peer within a | |
2967 | 120 second time span, the peer will be declared dead and all SAs and associated | |
2968 | eroutes will be cleared. | |
2969 | ||
2970 | In the second example R_U_THERE packets are sent every 60 seconds and the | |
2971 | parameter setting dpdaction=hold will put the eroute of the ruptured connection | |
2972 | into a %trap state, so that when new outgoing traffic will occur, the | |
2973 | correspondig connection will be automatically renegotiated as soon as the | |
2974 | peer is up again. | |
2975 | ||
2976 | It is recommended to use dpdaction=hold for statically defined connections and | |
2977 | dpdaction=clear for dynamic roadwarrior connections. The default value is | |
2978 | dpdaction=none, which disables DPD. | |
2979 | ||
2980 | ||
280f5aeb AS |
2981 | 14.4 IKE Mode Config Pull Mode |
2982 | ------------------------- | |
2983 | ||
997358a6 MW |
2984 | The IKE Mode Config protocol <draft-ietf-ipsec-isakmp-mode-cfg-04.txt> allows |
2985 | the dynamic assignment of virtual IP addresses and optional DNS and WINS server | |
280f5aeb AS |
2986 | information to IPsec clients. As a default the "Mode Config Pull Mode" is |
2987 | used where the client actively sends a Mode Config request to the server | |
2988 | in order to obtain a virtual IP. The server answers with a Mode Config reply | |
2989 | message containing the requested information. | |
997358a6 MW |
2990 | |
2991 | Client side configuration (carol): | |
2992 | ||
2993 | conn home | |
2994 | right=192.168.0.1 | |
2995 | rightsubnet=10.1.0.0/16 | |
2996 | rightid=@moon.strongswan.org | |
2997 | left=%defaultroute | |
2998 | leftsourceip=%modeconfig | |
2999 | leftcert=carolCert.pem | |
3000 | leftid=carol@strongswan.org | |
3001 | auto=start | |
3002 | ||
3003 | Server side configuration (moon): | |
3004 | ||
3005 | conn roadwarrior | |
3006 | right=%any | |
3007 | rightid=carol@strongswan.org | |
3008 | rightsourceip=10.3.0.1 | |
3009 | left=%defaultroute | |
3010 | leftsubnet=10.1.0.0/16 | |
3011 | leftcert=moonCert.pem | |
3012 | leftid=@moon.strongswan.org | |
3013 | auto=add | |
3014 | ||
3015 | The wildcard %modeconfig or %modecfg used in the leftsourceip parameter of the | |
3016 | client will trigger a Mode Config request. Currently the server will return | |
3017 | the virtual IP address defined by the rightsourceip parameter. In the future | |
3018 | an LDAP-based lookup mechanism will be supported. | |
3019 | ||
3020 | ||
280f5aeb AS |
3021 | 14.5 IKE Mode Config Push Mode |
3022 | ------------------------- | |
3023 | ||
3024 | Cisco VPN equipment uses the alternative "Mode Config Push Mode" where the | |
3025 | initiating clients waits for the server to push down a virtual address via | |
3026 | a Mode Config set message. The receipt is acknowledged by the client with a | |
3027 | Mode Config ack message. | |
3028 | ||
3029 | Mode Config Push Mode is activated by the parameter | |
3030 | ||
3031 | modeconfig=push | |
3032 | ||
3033 | as part of the connection definition in ipsec.conf. The default value is | |
3034 | modeconfig=pull. | |
3035 | ||
3036 | ||
3037 | 14.6 XAUTH - Extended Authentication | |
3038 | ------------------------------- | |
3039 | ||
3040 | The XAUTH protocol <draft-beaulieu-ike-xauth-02.txt> allows an extended | |
3041 | client authentication using e.g. a username/password paradigm in addition | |
3042 | to the IKE Main Mode authentication. Thus XAUTH can be used in conjunction | |
3043 | with Pre-Shared Keys (PSK) by defining | |
3044 | ||
3045 | authby=xauthpsk | |
3046 | ||
3047 | or with RSA signatures | |
3048 | ||
3049 | authby=xauthrsasig | |
3050 | ||
3051 | in the connection definition, correspondingly. strongSwan can act either as | |
3052 | an XAUTH client with | |
3053 | ||
3054 | xauth=client | |
3055 | ||
3056 | or as an XAUTH server with | |
3057 | ||
3058 | xauth=server | |
3059 | ||
3060 | with xauth=client being the default value. strongSwan integrates a default | |
3061 | implementation where the XAUTH user credentials are stored on both the | |
3062 | server and the client in the /etc/ipsec.secrets file, using the syntax | |
3063 | ||
3064 | : XAUTH john "rT6q!V2p" | |
3065 | ||
3066 | The client must not have more than one XAUTH entry whereas the server can | |
3067 | contain an unlimited number of user credentials in ipsec.secrets. | |
3068 | ||
3069 | Either the prompting on the client side or the verification of the user | |
3070 | credentials on the server side can be implemented as a customized XAUTH | |
3071 | dynamic library module. The corresponding library interface is defined | |
3072 | by the pluto/xauth.h header file. | |
3073 | ||
3074 | ||
997358a6 MW |
3075 | 15. Copyright statement and acknowledgements |
3076 | ---------------------------------------- | |
3077 | ||
3078 | ||
3079 | FreeS/WAN version base system: | |
3080 | ||
3081 | Copyright (c) 1999-2004 | |
3082 | Henry Spencer, Richard Guy Briggs, | |
3083 | D. Hugh Redelmeier, Sandy Harris, Claudia Schmeing, | |
3084 | Michael Richardson, Angelos D. Keromytis, John Ioannidis, | |
3085 | ||
3086 | NAT-Traversal, ipsec starter, Delete SA and Notification messages: | |
3087 | ||
3088 | Copyright (c) 2002-2003, Mathieu Lafon | |
3089 | ||
3090 | Additional cryptoalgorithms (AES, etc): | |
3091 | ||
3092 | Copyright (c) 2002-2003, JuanJo Ciarlante | |
3093 | ||
3094 | Dead Peer Detection: | |
3095 | ||
3096 | Copyright (c) 2002-2004 | |
3097 | Ken Bantoft, JuanJo Ciarlante, Philip Craig, | |
3098 | Pawel Krawczyk, Srinvasan Venkataraman | |
3099 | ||
3100 | Porting to Linux 2.6 kernel: | |
3101 | ||
3102 | Copyright (c) 2003, Herbert Xu | |
3103 | ||
3104 | Dynamic CRL fetching: | |
3105 | ||
3106 | Copyright (c) 2002, Stephane Laroche | |
3107 | ||
280f5aeb | 3108 | IKE Mode Config and XAUTH protocol: |
997358a6 MW |
3109 | |
3110 | Copyright (c) 2001-2002, Colubris Networks | |
3111 | ||
3112 | Virtual IP and source routing: | |
3113 | ||
3114 | Copyright (c) 2003, Tuomo Soini | |
3115 | ||
3116 | Port and protocol selectors for outbound traffic: | |
3117 | ||
3118 | Copyright (c) 2002, Stephen J. Bevan | |
3119 | ||
3120 | PGPnet-RSA parts of patch: | |
3121 | ||
3122 | Copyright (c) 2000, Kai Martius | |
3123 | ||
3124 | X.509, OCSP and smartcard functionality: | |
8af25c56 | 3125 | |
997358a6 MW |
3126 | Copyright (c) 2000, Andreas Hess, Patric Lichtsteiner, Roger Wegmann |
3127 | Copyright (c) 2001, Marco Bertossa, Andreas Schleiss | |
3128 | Copyright (c) 2002, Uli Galizzi, Ariane Seiler, Mario Strasser | |
3129 | Copyright (c) 2002, Martin Berner, Lukas Suter | |
3130 | Copyright (c) 2003, Christoph Gysin, Simon Zwahlen | |
3131 | Copyright (c) 2004, David Buechi, Michael Meier | |
3132 | Copyright (c) 2000-2005, Andreas Steffen | |
3133 | ||
3134 | Zurich University of Applied Sciences in Winterthur, Switzerland | |
3135 | ||
3136 | scepclient: | |
3137 | ||
3138 | Copyright (c) 2005, Jan Hutter, Martin Willi | |
280f5aeb | 3139 | Copyright (c) 2005-2007, Andreas Steffen |
997358a6 MW |
3140 | |
3141 | University of Applied Sciences in Rapperswil, Switzerland | |
3142 | ||
3143 | This program is free software; you can redistribute it and/or modify | |
3144 | it under the terms of the GNU General Public License as published by | |
3145 | the Free Software Foundation; either version 2 of the License, or | |
3146 | (at your option) any later version. See http://www.fsf.org/copyleft/gpl.txt. | |
3147 | ||
3148 | This program is distributed in the hope that it will be useful, but | |
3149 | WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY | |
3150 | or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
3151 | for more details. | |
3152 | ----------------------------------------------------------------------------- | |
3153 |