1 ----------------------------
2 strongSwan - Configuration
3 ----------------------------
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
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)
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
50 strongSwan is an OpenSource IPsec solution for Unix based operating systems.
52 This document is just a short introduction, for more detailed information
53 consult the manual pages and our wiki:
55 http://wiki.strongswan.org
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.
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:
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
79 Configuration on gateway moon:
81 /etc/ipsec.d/cacerts/strongswanCert.pem
83 /etc/ipsec.d/certs/moonCert.pem
87 : RSA moonKey.pem "<optional passphrase>"
92 leftsubnet=10.1.0.0/16
95 rightsubnet=10.2.0.0/16
96 rightid="C=CH, O=strongSwan, CN=sun.strongswan.org"
99 Configuration on gateway sun:
101 /etc/ipsec.d/cacerts/strongswanCert.pem
103 /etc/ipsec.d/certs/sunCert.pem
107 : RSA sunKey.pem "<optional passphrase>"
112 leftsubnet=10.2.0.0/16
115 rightsubnet=10.1.0.0/16
116 rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
120 2.2 Host-to-host case
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.
127 | 192.168.0.1 | === | 192.168.0.2 |
130 Configuration on host moon:
132 /etc/ipsec.d/cacerts/strongswanCert.pem
134 /etc/ipsec.d/certs/moonCert.pem
138 : RSA moonKey.pem "<optional passphrase>"
143 leftcert=moonCert.pem
145 rightid="C=CH, O=strongSwan, CN=sun.strongswan.org"
148 Configuration on host sun:
150 /etc/ipsec.d/cacerts/strongswanCert.pem
152 /etc/ipsec.d/certs/sunCert.pem
156 : RSA sunKey.pem "<optional passphrase>"
163 rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
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.
173 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
176 Configuration on gateway moon:
178 /etc/ipsec.d/cacerts/strongswanCert.pem
180 /etc/ipsec.d/certs/moonCert.pem
184 : RSA moonKey.pem "<optional passphrase>"
189 leftsubnet=10.1.0.0/16
190 leftcert=moonCert.pem
194 Configuration on roadwarrior carol:
196 /etc/ipsec.d/cacerts/strongswanCert.pem
198 /etc/ipsec.d/certs/carolCert.pem
202 : RSA carolKey.pem "<optional passphrase>"
207 leftcert=carolCert.pem
209 rightsubnet=10.1.0.0/16
210 rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
214 2.6 Roadwarrior case with virtual IP
215 --------------------------------
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.
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
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
228 rightsourceip=10.3.0.0/16
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
236 Configuration on gateway moon:
238 /etc/ipsec.d/cacerts/strongswanCert.pem
240 /etc/ipsec.d/certs/moonCert.pem
244 : RSA moonKey.pem "<optional passphrase>"
249 leftsubnet=10.1.0.0/16
250 leftcert=moonCert.pem
252 rightsourceip=10.3.0.0/16
255 Configuration on roadwarrior carol:
257 /etc/ipsec.d/cacerts/strongswanCert.pem
259 /etc/ipsec.d/certs/carolCert.pem
263 : RSA carolKey.pem "<optional passphrase>"
269 leftcert=carolCert.pem
271 rightsubnet=10.1.0.0/16
272 rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
276 3. Generating certificates and CRLs
277 --------------------------------
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.
284 3.1 Generating a CA certificate
285 ---------------------------
287 The OpenSSL statement
289 openssl req -x509 -days 1460 -newkey rsa:4096 \
290 -keyout strongswanKey.pem -out strongswanCert.pem
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).
295 openssl x509 -in cert.pem -noout -text
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.
300 If you prefer the CA certificate to be in binary DER format then the following
301 command achieves this transformation:
303 openssl x509 -in strongswanCert.pem -outform DER -out strongswanCert.der
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" \
311 ipsec pki --print --in strongswanCert.der
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.
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.
322 3.2 Generating a host or user certificate
323 -------------------------------------
325 The OpenSSL statement
327 openssl req -newkey rsa:2048 -keyout hostKey.pem \
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.
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:
337 subjectAltName=DNS:moon.strongswan.org
339 if you want to identify the host by its Fully Qualified Domain Name (FQDN), or
341 subjectAltName=IP:192.168.0.1
343 if you want the ID to be of type IPV4_ADDR. Of course you could include both
346 subjectAltName=DNS:moon.strongswan.org,IP:192.168.0.1
348 but the use of an IP address for the identification of a host should be
351 For user certificates the appropriate ID type is RFC822_ADDR which can be
354 subjectAltName=email:carol@strongswan.org
356 or if the user's e-mail address is part of the subject's distinguished name
358 subjectAltName=email:copy
360 Now the certificate request can be signed by the CA with the command
362 openssl ca -in hostReq.pem -days 730 -out hostCert.pem -notext
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
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
374 crlDistributionPoints=@crl_dp
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"
382 If you have only a single HTTP distribution point then the short form
384 crlDistributionPoints="URI:http://crl.strongswan.org/strongswan.crl"
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
397 do something thing similar using the strongSwan PKI tool.
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:
403 openssl pkcs12 -export -inkey carolKey.pem \
404 -in carolCert.pem -name "carol" \
405 -certfile strongswanCert.pem -caname "strongSwan Root CA" \
412 An empty CRL that is signed by the CA can be generated with the command
414 openssl ca -gencrl -crldays 15 -out crl.pem
416 If you omit the -crldays option then the default_crl_days value (30 days)
417 specified in openssl.cnf is used.
419 If you prefer the CRL to be in binary DER format then this conversion
422 openssl crl -in crl.pem -outform DER -out cert.crl
424 The strongSwan PKI tool provides the ipsec pki --signcrl command to sign CRLs.
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
431 3.4 Revoking a certificate
432 ----------------------
434 A specific host certificate stored in the file host.pem is revoked with the
437 openssl ca -revoke host.pem
439 Next the CRL file must be updated
441 openssl ca -gencrl -crldays 60 -out crl.pem
443 The content of the CRL file can be listed with the command
445 openssl crl -in crl.pem -noout -text
447 in the case of a base64 CRL, or alternatively for a CRL in DER format
449 openssl crl -inform DER -in cert.crl -noout -text
451 Again the ipsec pki --signcrl command may be used to create new CRLs containing
452 additional certificates.
455 4. Configuring the connections - ipsec.conf
456 ----------------------------------------
458 4.1 Configuring my side
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
468 leftcert=moonCert.pem
469 # load connection definitions automatically
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
476 leftcert=moonCert.pem
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
482 leftcert=moonCert.der
486 leftcert=moonCert.cer
488 would also be valid alternatives.
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
496 leftcert=mycerts/moonCert.pem
498 Absolute pathnames are also possible as in
500 leftcert=/usr/ssl/certs/moonCert.pem
502 As an ID for the VPN gateway we recommend the use of a Fully Qualified Domain
503 Name (FQDN) of the form
507 leftid=@moon.strongswan.org
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.
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
520 leftid="C=CH, O=strongSwan, CN=moon.strongswan.org"
522 Since the subject's DN is part of the certificate, the leftid does not have to
523 be declared explicitly. Thus the entry
528 automatically assumes the subject DN of leftcert to be the host ID.
531 4.2 Multiple certificates
532 ---------------------
534 strongSwan supports multiple local host certificates and corresponding
539 rightid=@peer1.domain1
541 # leftid is DN of myCert1
545 rightid=@peer2.domain2
547 # leftid is DN of myCert2
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.
554 4.3 Configuring the peer side using CA certificates
555 -----------------------------------------------
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:
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.
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
580 rightid="C=CH, O=strongSwan IPsec, CN=sun.strongswan.org"
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.
587 The Relative Distinguished Names (RDNs) can alternatively be separated by a
588 slash '/' instead of a comma ','
590 rightid="/C=CH/O=strongSwan IPsec/CN=sun.strongswan.org"
592 This is the representation extracted from the certificate by the OpenSSL
595 openssl x509 -in sunCert.pem -noout -subject
597 The following RDNs are supported by strongSwan
599 +-------------------------------------------------------+
600 | DC Domain Component |
601 |-------------------------------------------------------|
603 |-------------------------------------------------------|
604 | ST State or province |
605 |-------------------------------------------------------|
606 | L Locality or town |
607 |-------------------------------------------------------|
609 |-------------------------------------------------------|
610 | OU Organizational Unit |
611 |-------------------------------------------------------|
613 |-------------------------------------------------------|
614 | ND NameDistinguisher, used with CN |
615 |-------------------------------------------------------|
617 |-------------------------------------------------------|
619 |-------------------------------------------------------|
621 |-------------------------------------------------------|
623 |-------------------------------------------------------|
625 |-------------------------------------------------------|
627 |-------------------------------------------------------|
629 |-------------------------------------------------------|
630 | emailAddress E-mail |
631 |-------------------------------------------------------|
633 |-------------------------------------------------------|
634 | serialNumber Serial number |
635 |-------------------------------------------------------|
637 |-------------------------------------------------------|
638 | ID X.500 Unique Identifier |
639 |-------------------------------------------------------|
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 +-------------------------------------------------------+
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
667 leftsubnet=10.1.0.0/24
671 leftsubnet=10.1.3.0/24
673 For IKEv2 connections this can even be simplified by using
675 leftsubnet=10.1.0.0/24,10.1.3.0/24
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:
686 rightid=@sun.strongswan.org
690 rightid=carol@strongswan.org
694 rightid="C=CH, O=strongSwan, CN=dave@strongswan.org"
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.
702 rightid=@sun.strongswan.org
706 rightid=carol@strongswan.org
710 rightid="C=CH, O=strongSwan, CN=dave@strongswan.org"
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
721 4.4 Handling Virtual IPs and narrowing
722 ----------------------------------
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:
735 righsubnet=10.4.0.5/32
739 rightsubnet=10.4.0.47/32
743 rightsubnet=10.4.0.128/28
745 Because the charon daemon uses narrowing (even for IKEv1) these three entries
746 can be reduced to the single connection definition
750 rightsubnet=10.4.0.0/24
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
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.
761 4.5 Protocol and Port Selectors
762 ---------------------------
764 strongSwan offer the possibility to restrict the protocol and optionally the
765 ports in an IPsec SA using the rightprotoport and leftprotoport parameters.
772 leftid=@moon.strongswan.org
778 leftid=@moon.strongswan.org
781 conn l2tp # with port wildcard for Mac OS X Panther interoperability
783 rightprotoport=17/%any
784 leftid=@moon.strongswan.org
785 leftprotoport=17/1701
789 rightprotoport=udp/bootpc
790 leftid=@moon.strongswan.org
791 leftsubnet=0.0.0.0/0 #allows DHCP discovery broadcast
792 leftprotoport=udp/bootps
798 Protocols and ports can be designated either by their numerical values
799 or by their acronyms defined in /etc/services.
803 shows the following connection definitions:
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
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
815 4.6 IPsec policies based on wildcards
816 ---------------------------------
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).
824 Let's make a practical example:
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.
837 The IPsec policy defined above can now be enforced with the following three
838 IPsec security associations:
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
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
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
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.
865 "C=CH, O=ACME, OU=Research, OU=Special Effects, CN=Bart Simpson"
867 matches the templates
869 "C=CH, O=ACME, OU=Research, OU=*, CN=*"
871 "C=CH, O=ACME, OU=*, OU=Special Effects, CN=*"
873 "C=CH, O=ACME, OU=*, OU=*, CN=*"
877 "C=CH, O=ACME, OU=*, CN=*"
879 which doesn't have the same number of RDNs.
882 4.7 IPsec policies based on CA certificates
883 ---------------------------------------
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
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
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
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
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.
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
925 sets the CA requested from the peer to the CA used by the left side itself
931 leftcert=mySalesCert.pem
934 5. Configuring certificates and CRLs
935 ---------------------------------
938 5.1 Installing the CA certificates
939 ------------------------------
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
948 /etc/ipsec.d/cacerts/
951 5.2 Installing optional certificate revocation lists (CRLs)
952 -------------------------------------------------------
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.
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.
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.
975 5.3 Dynamic update of certificates and CRLs
976 ---------------------------------------
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:
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 |
1005 |---------------------------------------------------------------------------|
1006 | ipsec purgeocsp purge the OCSP cache and fetching requests |
1007 +---------------------------------------------------------------------------+
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.
1013 5.4 Local caching of CRLs
1014 ---------------------
1016 The the ipsec.conf option
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
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.
1031 5.5 Online Certificate Status Protocol (OCSP)
1032 -----------------------------------------
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
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:
1046 cacert=strongswanCert.pem
1047 ocspuri=http://ocsp.strongswan.org:8880
1050 The HTTP port can be freely chosen.
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
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
1060 The command consists of the parameters
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.
1069 -CA the CA certificate
1071 -port the HTTP port the OCSP server is listening on.
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.
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.
1083 -resp_no_certs With this option the OCSP signer certificate defined by
1084 -rsigner is not included in the OCSP response.
1086 -nmin the validity interval of an OCSP response given in minutes.
1088 -text this option activates a verbose logging output, showing the contents
1089 of both the received OCSP request and sent OCSP response.
1092 The OCSP signer certificate can either be put into the default directory
1094 /etc/ipsec.d/ocspcerts
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
1101 extendedKeyUsage=OCSPSigner
1103 in the [ usr_cert ] section of your openssl.cnf configuration file before
1104 the CA signs the OCSP server certificate.
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
1110 authorityInfoAccess = OCSP;URI:http://ocsp.strongswan.org:8880
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.
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
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:
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.
1142 As mentioned earlier the default setting is "strictcrlpolicy=no"
1145 5.7 Configuring the peer side using locally stored certificates
1146 -----------------------------------------------------------
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.
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
1159 rightid=@sun.strongswan.org
1160 rightcert=sunCert.cer
1164 rightcert=carolCert.der
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
1173 to the connection definition[s] in order to avoid the sending of the host's
1174 own certificate. The default value is
1176 leftsendcert=ifasked
1178 If a peer does not send a certificate request then use the setting
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.
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
1191 rightcert=peercerts/carolCert.der
1195 rightcert=/usr/ssl/certs/carolCert.der
1198 6. Configuring the private keys - ipsec.secrets
1199 --------------------------------------------
1201 6.1 Loading private key files in PKCS#1 or PKCS#8 format
1202 ----------------------------------------------------
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.
1208 RSA private key files are declared in /etc/ipsec.secrets using the syntax
1210 : RSA <my keyfile> "<optional passphrase>"
1212 The key file can be either in base64 PEM-format or binary DER-format. The
1213 actual coding is detected automatically. The example
1217 uses a pathname relative to the default directory
1219 /etc/ipsec.d/private
1221 As an alternative an absolute pathname can be given as in
1223 : RSA /usr/ssl/private/moonKey.pem
1225 In both cases make sure that the key files are root readable only.
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
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
1237 openssl rsa -in moonKey.pem -out moonKey.pem
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
1243 : RSA moonKey.pem "This is my passphrase"
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
1249 openssl pkcs12 -nocerts -in moonCert.p12 -out moonKey.pem
1251 if the key file moonKey.pem is to be secured again by a passphrase, or
1253 openssl pkcs12 -nocerts -nodes -in moonCert.p12 -out moonKey.pem
1255 if the private key is to be stored unlocked.
1258 6.2 Entering passphrases interactively
1259 ----------------------------------
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
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
1274 : RSA moonKey.pem %prompt
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
1282 which actually is an alias for the existing command
1286 and which causes a passphrase prompt to appear. To abort entering a passphrase
1287 enter just a carriage return.
1290 6.3 Multiple private keys
1291 ---------------------
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
1298 : RSA myKey1.pem "<optional passphrase1>"
1300 : RSA myKey2.pem "<optional passphrase2>"
1303 7. Configuring CA properties - ipsec.conf
1304 --------------------------------------
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:
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"
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.
1321 Each ca section is named with a unique label
1325 The only mandatory parameter is
1327 cacert=strongswanCert.pem
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
1335 ocspuri=http://ocsp.strongswan.org:8880
1337 allows to define an individual OCSP server per CA. Also up to two additional
1338 CRL distribution points (CDPs) can be defined
1340 crluri=http://crl.strongswan.org/strongswan.crl'
1341 crluri2="ldap://ldap.strongswan.org/O=strongSwan, C=CH?certificateRevocationList"
1343 which are added to any CDPs already present in the received certificates
1346 With the auto=add statement the ca definition is automatically loaded during
1347 startup. Setting auto=ignore will ignore the ca section.
1349 Any parameters which appear in several ca definitions can be put in
1350 a common ca %default section
1353 crluri=http://crl.strongswan.org/strongswan.crl'
1356 8. Monitoring functions
1357 --------------------
1359 strongSwan offers the following monitoring functions:
1365 lists all IKE cryptographic algorithms that are currently
1366 registered with strongSwan.
1371 ipsec listcerts [--utc]
1373 lists all local certificates, both strongSwan's own and those of
1374 trusted peer loaded via leftcert and rightcert, respectively.
1379 ipsec listcacerts [--utc]
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.
1387 ipsec listaacerts [--utc]
1389 lists all Authorization Authority certificates that have been loaded from
1390 the directory /etc/ipsec.d/aacerts/.
1395 ipsec listocspcerts [--utc]
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
1404 ipsec listacerts [--utc]
1406 lists all X.509 attribute certificates that have been loaded from the directory
1407 /etc/ipsec.d/acerts/.
1412 ipsec listcainfos [--utc]
1414 lists the properties defined by the ca definition sections in ipsec.conf.
1419 ipsec listcrls [--utc]
1421 lists all CRLs that have been loaded from /etc/ipsec.d/crls/.
1427 ipsec listocsp [--utc]
1429 lists the contents of the OCSP response cache.
1434 ipsec listall [--utc]
1436 is equivalent to using all of the above commands.
1439 9. Firewall support functions
1440 --------------------------
1443 9.1 Environment variables in the updown script
1444 ------------------------------------------
1446 strongSwan makes the following environment variables available
1447 in the updown script indicated by the leftupdown option:
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 +-------------------------------------------------------------------+
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,
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.
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.
1481 (4) $PLUTO_PEER_CA contains the distinguished name of the CA that
1482 issued the peer's certificate.
1484 There are several more, refer to the provided default script for a documentation
1488 9.2 Automatic insertion and deletion of iptables firewall rules
1489 -----------------------------------------------------------
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
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:
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
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