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