NEWS: Some minor updates
[strongswan.git] / README.md
index aa40fe3..f26e597 100644 (file)
--- a/README.md
+++ b/README.md
-                 ----------------------------
-                  strongSwan - Configuration
-                 ----------------------------
-
-
-Contents
---------
-
-   1. Overview
-   2. Quickstart
-    2.1 Site-to-Site case
-    2.2 Host-to-Host case
-    2.3 Roadwarrior case
-    2.4 Roadwarrior case with virtual IP
-   3. Generating X.509 certificates and CRLs
-    3.1 Generating a CA certificate
-    3.2 Generating a host or user certificate
-    3.3 Generating a CRL
-    3.4 Revoking a certificate
-   4. Configuring the connections - ipsec.conf
-    4.1 Configuring my side
-    4.2 Multiple certificates
-    4.3 Configuring the peer side using CA certificates
-    4.4 Handling Virtual IPs and wildcard subnets
-    4.5 Protocol and port selectors
-    4.6 IPsec policies based on wildcards
-    4.7 IPsec policies based on CA certificates
-   5. Configuring certificates and CRLs
-    5.1 Installing CA certificates
-    5.2 Installing optional Certificate Revocation Lists (CRLs)
-    5.3 Dynamic update of certificates and CRLs
-    5.4 Local caching of CRLs
-    5.5 Online Certificate Status Protocol (OCSP)
-    5.6 CRL policy
-    5.7 Configuring the peer side using locally stored certificates
-   6. Configuring the private keys - ipsec.secrets
-    6.1 Loading private key files in PKCS#1 format
-    6.2 Entering passphrases interactively
-    6.3 Multiple private keys
-   7. Configuring CA properties - ipsec.conf
-   8. Monitoring functions
-   9. Firewall support functions
-       9.1 Environment variables in the updown script
-       9.2 Automatic insertion and deletion of iptables firewall rules
-
-
-1. Overview
-   --------
-
-strongSwan is an OpenSource IPsec solution for Unix based operating systems.
-
-This document is just a short introduction, for more detailed information
-consult the manual pages and our wiki:
-
-    http://wiki.strongswan.org
-
-
-2. Quickstart
-   ----------
-
-In the following examples we assume for reasons of clarity that left designates
-the local host and that right is the remote host.  Certificates for users,
-hosts and gateways are issued by a fictitious strongSwan CA.  How to generate
-private keys and certificates using OpenSSL or the strongSwan PKI tool will be
-explained in section 3.  The CA certificate "strongswanCert.pem" must be present
-on all VPN end points in order to be able to authenticate the peers.
-
-
-2.1 Site-to-site case
-    -----------------
-
-In this scenario two security gateways moon and sun will connect the
-two subnets moon-net and sun-net with each other through a VPN tunnel
-set up between the two gateways:
-
-    10.1.0.0/16 -- | 192.168.0.1 | === | 192.168.0.2 | -- 10.2.0.0/16
-      moon-net          moon                 sun           sun-net
-
-Configuration on gateway moon:
+# strongSwan Configuration #
 
-    /etc/ipsec.d/cacerts/strongswanCert.pem
+## Overview ##
 
-    /etc/ipsec.d/certs/moonCert.pem
+strongSwan is an OpenSource IPsec-based VPN solution.
 
-    /etc/ipsec.secrets:
+This document is just a short introduction of the strongSwan **swanctl** command
+which uses the modern [**vici**](src/libcharon/plugins/vici/README.md) *Versatile
+IKE Configuration Interface*. The deprecated **ipsec** command using the legacy
+**stroke** configuration interface is described [**here**](README_LEGACY.md).
+For more detailed information consult the man pages and
+[**our wiki**](http://wiki.strongswan.org).
 
-        : RSA moonKey.pem "<optional passphrase>"
 
-    /etc/ipsec.conf:
+## Quickstart ##
 
-        conn net-net
-            leftsubnet=10.1.0.0/16
-            leftcert=moonCert.pem
-            right=192.168.0.2
-            rightsubnet=10.2.0.0/16
-            rightid="C=CH, O=strongSwan, CN=sun.strongswan.org"
-            auto=start
+Certificates for users, hosts and gateways are issued by a fictitious
+strongSwan CA. In our example scenarios the CA certificate `strongswanCert.pem`
+must be present on all VPN endpoints in order to be able to authenticate the
+peers. For your particular VPN application you can either use certificates from
+any third-party CA or generate the needed private keys and certificates yourself
+with the strongSwan **pki** tool, the use of which will be explained in one of
+the sections following below.
 
-Configuration on gateway sun:
 
-    /etc/ipsec.d/cacerts/strongswanCert.pem
+### Site-to-Site Case ###
 
-    /etc/ipsec.d/certs/sunCert.pem
-
-    /etc/ipsec.secrets:
-
-        : RSA sunKey.pem "<optional passphrase>"
-
-    /etc/ipsec.conf:
-
-        conn net-net
-            leftsubnet=10.2.0.0/16
-            leftcert=sunCert.pem
-            right=192.168.0.1
-            rightsubnet=10.1.0.0/16
-            rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
-            auto=start
+In this scenario two security gateways _moon_ and _sun_ will connect the
+two subnets _moon-net_ and _sun-net_ with each other through a VPN tunnel
+set up between the two gateways:
 
+    10.1.0.0/16 -- | 192.168.0.1 | === | 192.168.0.2 | -- 10.2.0.0/16
+      moon-net          moon                 sun           sun-net
 
-2.2 Host-to-host case
-    -----------------
+Configuration on gateway _moon_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/private/moonKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+        connections {
+            net-net {
+                remote_addrs = 192.168.0.2
+
+                local {
+                    auth = pubkey
+                    certs = moonCert.pem
+                }
+                remote {
+                    auth = pubkey
+                    id = "C=CH, O=strongSwan, CN=sun.strongswan.org"
+                }
+                children {
+                    net-net {
+                        local_ts  = 10.1.0.0/16
+                        remote_ts = 10.2.0.0/16
+                        start_action = trap
+                   }
+                }
+            }
+        }
+
+Configuration on gateway _sun_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/sunCert.pem
+    /etc/swanctl/private/sunKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+        connections {
+            net-net {
+                remote_addrs = 192.168.0.1
+
+                local {
+                    auth = pubkey
+                    certs = sunCert.pem
+                }
+                remote {
+                    auth = pubkey
+                    id = "C=CH, O=strongSwan, CN=moon.strongswan.org"
+                }
+                children {
+                    net-net {
+                        local_ts  = 10.2.0.0/16
+                        remote_ts = 10.1.0.0/16
+                        start_action = trap
+                   }
+                }
+            }
+        }
+
+The local and remote identities used in this scenario are the
+*subjectDistinguishedNames* contained in the end entity certificates.
+The certificates and private keys are loaded into the **charon** daemon with
+the command
+
+    swanctl --load-creds
+
+whereas
+
+    swanctl --load-conns
+
+loads the connections defined in `swanctl.conf`. With `start_action = trap` the
+IPsec connection is automatically set up with the first plaintext payload IP
+packet wanting to go through the tunnel.
+
+### Host-to-Host Case ###
 
 This is a setup between two single hosts which don't have a subnet behind
 them.  Although IPsec transport mode would be sufficient for host-to-host
@@ -127,45 +116,64 @@ connections we will use the default IPsec tunnel mode.
     | 192.168.0.1 | === | 192.168.0.2 |
          moon                sun
 
-Configuration on host moon:
-
-    /etc/ipsec.d/cacerts/strongswanCert.pem
-
-    /etc/ipsec.d/certs/moonCert.pem
-
-    /etc/ipsec.secrets:
-
-        : RSA moonKey.pem "<optional passphrase>"
-
-    /etc/ipsec.conf:
-
-        conn host-host
-            leftcert=moonCert.pem
-            right=192.168.0.2
-            rightid="C=CH, O=strongSwan, CN=sun.strongswan.org"
-            auto=start
-
-Configuration on host sun:
-
-    /etc/ipsec.d/cacerts/strongswanCert.pem
-
-    /etc/ipsec.d/certs/sunCert.pem
-
-    /etc/ipsec.secrets:
-
-        : RSA sunKey.pem "<optional passphrase>"
-
-    /etc/ipsec.conf:
-
-        conn host-host
-            leftcert=sunCert.pem
-            right=192.168.0.1
-            rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
-            auto=start
-
-
-2.3 Roadwarrior case
-    ----------------
+ Configuration on host _moon_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/private/moonKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+        connections {
+            host-host {
+                remote_addrs = 192.168.0.2
+
+                local {
+                    auth=pubkey
+                    certs = moonCert.pem
+                }
+                remote {
+                    auth = pubkey
+                    id = "C=CH, O=strongSwan, CN=sun.strongswan.org"
+                }
+                children {
+                    net-net {
+                        start_action = trap
+                    }
+                }
+            }
+        }
+
+Configuration on host _sun_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/sunCert.pem
+    /etc/swanctl/private/sunKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+        connections {
+            host-host {
+                remote_addrs = 192.168.0.1
+
+                local {
+                    auth = pubkey
+                    certs = sunCert.pem
+                }
+                remote {
+                    auth = pubkey
+                    id = "C=CH, O=strongSwan, CN=moon.strongswan.org"
+                }
+                children {
+                    host-host {
+                        start_action = trap
+                   }
+                }
+            }
+        }
+
+
+### Roadwarrior Case ###
 
 This is a very common case where a strongSwan gateway serves an arbitrary
 number of remote VPN clients usually having dynamic IP addresses.
@@ -173,1342 +181,513 @@ number of remote VPN clients usually having dynamic IP addresses.
     10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
       moon-net          moon              carol
 
-Configuration on gateway moon:
-
-    /etc/ipsec.d/cacerts/strongswanCert.pem
-
-    /etc/ipsec.d/certs/moonCert.pem
-
-    /etc/ipsec.secrets:
-
-        : RSA moonKey.pem "<optional passphrase>"
-
-    /etc/ipsec.conf:
-
-        conn rw
-            leftsubnet=10.1.0.0/16
-            leftcert=moonCert.pem
-            right=%any
-            auto=add
-
-Configuration on roadwarrior carol:
-
-    /etc/ipsec.d/cacerts/strongswanCert.pem
-
-    /etc/ipsec.d/certs/carolCert.pem
-
-    /etc/ipsec.secrets:
-
-        : RSA carolKey.pem "<optional passphrase>"
-
-    /etc/ipsec.conf:
-
-        conn home
-            leftcert=carolCert.pem
-            right=192.168.0.1
-            rightsubnet=10.1.0.0/16
-            rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
-            auto=start
-
-
-2.6 Roadwarrior case with virtual IP
-    --------------------------------
+Configuration on gateway _moon_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/private/moonKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+        connections {
+            rw {
+                local {
+                    auth = pubkey
+                    certs = moonCert.pem
+                    id = moon.strongswan.org
+                }
+                remote {
+                    auth = pubkey
+                }
+                children {
+                    net-net {
+                        local_ts  = 10.1.0.0/16
+                    }
+                }
+            }
+        }
+
+Configuration on roadwarrior _carol_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/carolCert.pem
+    /etc/swanctl/private/carolKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+         connections {
+            home {
+                remote_addrs = moon.strongswan.org
+
+                local {
+                    auth = pubkey
+                    certs = carolCert.pem
+                    id = carol@strongswan.org
+                }
+                remote {
+                    auth = pubkey
+                    id = moon.strongswan.org
+                }
+                children {
+                    home {
+                        local_ts  = 10.1.0.0/16
+                        start_action = start
+                    }
+                }
+            }
+        }
+
+For `remote_addrs` the hostname `moon.strongswan.org` was chosen which will be
+resolved by DNS at runtime into the corresponding IP destination address.
+In this scenario the identity of the roadwarrior `carol` is the email address
+`carol@strongswan.org` which must be included as a *subjectAlternativeName* in
+the roadwarrior certificate `carolCert.pem`.
+
+
+### Roadwarrior Case with Virtual IP ###
 
 Roadwarriors usually have dynamic IP addresses assigned by the ISP they are
-currently attached to.  In order to simplify the routing from moon-net back
-to the remote access client carol it would be desirable if the roadwarrior had
-an inner IP address chosen from a pre-assigned pool.
+currently attached to.  In order to simplify the routing from _moon-net_ back
+to the remote access client _carol_ it would be desirable if the roadwarrior had
+an inner IP address chosen from a pre-defined pool.
 
     10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x | -- 10.3.0.1
       moon-net          moon              carol       virtual IP
 
 In our example the virtual IP address is chosen from the address pool
-10.3.0.0/16 which can be configured by adding the parameter
-
-    rightsourceip=10.3.0.0/16
-
-to the gateway's ipsec.conf.  To request an IP address from this pool a
-roadwarrior can use IKEv1 mode config or IKEv2 configuration payloads.
-The configuration for both is the same
-
-    leftsourceip=%config
-
-Configuration on gateway moon:
-
-    /etc/ipsec.d/cacerts/strongswanCert.pem
-
-    /etc/ipsec.d/certs/moonCert.pem
-
-    /etc/ipsec.secrets:
-
-        : RSA moonKey.pem "<optional passphrase>"
-
-    /etc/ipsec.conf:
-
-        conn rw
-            leftsubnet=10.1.0.0/16
-            leftcert=moonCert.pem
-            right=%any
-            rightsourceip=10.3.0.0/16
-            auto=add
-
-Configuration on roadwarrior carol:
-
-    /etc/ipsec.d/cacerts/strongswanCert.pem
-
-    /etc/ipsec.d/certs/carolCert.pem
-
-    /etc/ipsec.secrets:
-
-        : RSA carolKey.pem "<optional passphrase>"
-
-    /etc/ipsec.conf:
-
-        conn home
-            leftsourceip=%config
-            leftcert=carolCert.pem
-            right=192.168.0.1
-            rightsubnet=10.1.0.0/16
-            rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
-            auto=start
-
+`10.3.0.0/16` which can be configured by adding the section
+
+    pools {
+        rw_pool {
+            addrs = 10.3.0.0/16
+        }
+    }
+
+to the gateway's `swanctl.conf` from where they are loaded into the **charon**
+daemon using the command
+
+    swanctl --load-pools
+
+To request an IP address from this pool a roadwarrior can use IKEv1 mode config
+or IKEv2 configuration payloads. The configuration for both is the same
+
+    vips = 0.0.0.0
+
+Configuration on gateway _moon_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/private/moonKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+        connections {
+            rw {
+                pools = rw_pool
+
+                local {
+                    auth = pubkey
+                    certs = moonCert.pem
+                    id = moon.strongswan.org
+                }
+                remote {
+                    auth = pubkey
+                }
+                children {
+                    net-net {
+                        local_ts  = 10.1.0.0/16
+                    }
+                }
+            }
+        }
+
+        pools {
+            rw_pool {
+                addrs = 10.30.0.0/16
+            }
+        }
+
+Configuration on roadwarrior _carol_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/carolCert.pem
+    /etc/swanctl/private/carolKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+         connections {
+            home {
+                remote_addrs = moon.strongswan.org
+                vips = 0.0.0.0
+
+                local {
+                    auth = pubkey
+                    certs = carolCert.pem
+                    id = carol@strongswan.org
+                }
+                remote {
+                    auth = pubkey
+                    id = moon.strongswan.org
+                }
+                children {
+                    home {
+                        local_ts  = 10.1.0.0/16
+                        start_action = start
+                    }
+                }
+            }
+        }
+
+
+### Roadwarrior Case with EAP Authentication ###
 
-3. Generating certificates and CRLs
-   --------------------------------
-
-This section is not a full-blown tutorial on how to use OpenSSL or the
-strongSwan PKI tool.  It just lists a few points that are relevant if you want
-to generate your own certificates and CRLs for use with strongSwan.
-
-
-3.1 Generating a CA certificate
-    ---------------------------
-
-The OpenSSL statement
-
-    openssl req -x509 -days 1460 -newkey rsa:4096 \
-                -keyout strongswanKey.pem -out strongswanCert.pem
-
-creates a 4096 bit RSA private key strongswanKey.pem and a self-signed CA
-certificate strongswanCert.pem with a validity of 4 years (1460 days).
-
-    openssl x509 -in cert.pem -noout -text
-
-lists the properties of  a X.509 certificate cert.pem. It allows you to verify
-whether the configuration defaults in openssl.cnf have been inserted correctly.
-
-If you prefer the CA certificate to be in binary DER format then the following
-command achieves this transformation:
-
-     openssl x509 -in strongswanCert.pem -outform DER -out strongswanCert.der
-
-The statements
-
-    ipsec pki --gen -s 4096 > strongswanKey.der
-    ipsec pki --self --ca --lifetime 1460 --in strongswanKey.der \
-              --dn "C=CH, O=strongSwan, CN=strongSwan Root CA" \
-              > strongswanCert.der
-    ipsec pki --print --in strongswanCert.der
-
-achieve about the same with the strongSwan PKI tool.  Unlike OpenSSL the tool
-stores keys and certificates in the binary DER format by default.  The --outform
-option may be used to write PEM encoded files.
-
-The directory /etc/ipsec.d/cacerts contains all required CA certificates either
-in binary DER or in base64 PEM format, irrespective of the file suffix the
-correct format will be determined.
-
-
-3.2 Generating a host or user certificate
-    -------------------------------------
-
-The OpenSSL statement
+This is a very common case where a strongSwan gateway serves an arbitrary
+number of remote VPN clients which authenticate themselves via a password
+based *Extended Authentication Protocol* as e.g. *EAP-MD5* or *EAP-MSCHAPv2*.
 
-     openssl req -newkey rsa:2048 -keyout hostKey.pem \
-                 -out hostReq.pem
+    10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
+      moon-net          moon              carol
 
-generates a 2048 bit RSA private key hostKey.pem and a certificate request
-hostReq.pem which has to be signed by the CA.
+Configuration on gateway _moon_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/private/moonKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+        connections {
+            rw {
+                local {
+                    auth = pubkey
+                    certs = moonCert.pem
+                    id = moon.strongswan.org
+                }
+                remote {
+                    auth = eap-md5
+                }
+                children {
+                    net-net {
+                        local_ts  = 10.1.0.0/16
+                    }
+                }
+                send_certreq = no
+            }
+        }
+
+The  `swanctl.conf` file additionally contains a `secrets` section defining all
+client credentials
+
+       secrets {
+           eap-carol {
+               id = carol@strongswan.org
+               secret = Ar3etTnp
+           }
+           eap-dave {
+               id = dave@strongswan.org
+               secret = W7R0g3do
+           }
+       }
+
+Configuration on roadwarrior _carol_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+
+    /etc/swanctl/swanctl.conf:
+
+         connections {
+            home {
+                remote_addrs = moon.strongswan.org
+
+                local {
+                    auth = eap
+                    id = carol@strongswan.org
+                }
+                remote {
+                    auth = pubkey
+                    id = moon.strongswan.org
+                }
+                children {
+                    home {
+                        local_ts  = 10.1.0.0/16
+                        start_action = start
+                    }
+                }
+            }
+        }
+
+       secrets {
+           eap-carol {
+               id = carol@strongswan.org
+               secret = Ar3etTnp
+           }
+       }
+
+
+### Roadwarrior Case with EAP Identity ###
+
+Often a client EAP identity is exchanged via EAP which differs from the
+external IKEv2 identity. In this example the IKEv2 identity defaults to
+the IPv4 address of the client.
 
-If you want to add a subjectAltName field to the host certificate you must edit
-the OpenSSL configuration file openssl.cnf and add the following line in the
-[ usr_cert ] section:
+    10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
+      moon-net          moon              carol
 
-     subjectAltName=DNS:moon.strongswan.org
+Configuration on gateway _moon_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/private/moonKey.pem
+
+    /etc/swanctl/swanctl.conf:
+
+        connections {
+            rw {
+                local {
+                    auth = pubkey
+                    certs = moonCert.pem
+                    id = moon.strongswan.org
+                }
+                remote {
+                    auth = eap-md5
+                    eap_id = %any
+                }
+                children {
+                    net-net {
+                        local_ts  = 10.1.0.0/16
+                    }
+                }
+                send_certreq = no
+            }
+        }
+
+       secrets {
+           eap-carol {
+               id = carol
+               secret = Ar3etTnp
+           }
+           eap-dave {
+               id = dave
+               secret = W7R0g3do
+           }
+       }
+
+Configuration on roadwarrior _carol_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+
+    /etc/swanctl/swanctl.conf:
+
+         connections {
+            home {
+                remote_addrs = moon.strongswan.org
+
+                local {
+                    auth = eap
+                    eap_id = carol
+                }
+                remote {
+                    auth = pubkey
+                    id = moon.strongswan.org
+                }
+                children {
+                    home {
+                        local_ts  = 10.1.0.0/16
+                        start_action = start
+                    }
+                }
+            }
+        }
+
+       secrets {
+           eap-carol {
+               id = carol
+               secret = Ar3etTnp
+           }
+       }
 
-if you want to identify the host by its Fully Qualified Domain Name (FQDN), or
 
-     subjectAltName=IP:192.168.0.1
+## Generating Certificates and CRLs ##
 
-if you want the ID to be of type IPV4_ADDR. Of course you could include both
-ID types with
+This section is not a full-blown tutorial on how to use the strongSwan **pki**
+tool. It just lists a few points that are relevant if you want to generate your
+own certificates and CRLs for use with strongSwan.
+
+
+### Generating a CA Certificate ###
+
+The pki statement
+
+    pki --gen --type ed25519 --outform pem > strongswanKey.pem
+
+generates an elliptic Edwards-Curve key with a cryptographic strength of 128
+bits. The corresponding public key is packed into a self-signed CA certificate
+with a lifetime of 10 years (3652 days)
+
+    pki --self --ca --lifetime 3652 --in strongswanKey.pem \
+               --dn "C=CH, O=strongSwan, CN=strongSwan Root CA" \
+               --outform pem > strongswanCert.pem
+
+which can be listed with the command
+
+    pki --print --in strongswanCert.pem
+
+    subject:  "C=CH, O=strongSwan, CN=strongSwan Root CA"
+    issuer:   "C=CH, O=strongSwan, CN=strongSwan Root CA"
+    validity:  not before May 18 08:32:06 2017, ok
+               not after  May 18 08:32:06 2027, ok (expires in 3651 days)
+    serial:    57:e0:6b:3a:9a:eb:c6:e0
+    flags:     CA CRLSign self-signed
+    subjkeyId: 2b:95:14:5b:c3:22:87:de:d1:42:91:88:63:b3:d5:c1:92:7a:0f:5d
+    pubkey:    ED25519 256 bits
+    keyid:     a7:e1:6a:3f:e7:6f:08:9d:89:ec:23:92:a9:a1:14:3c:78:a8:7a:f7
+    subjkey:   2b:95:14:5b:c3:22:87:de:d1:42:91:88:63:b3:d5:c1:92:7a:0f:5d
+
+If you prefer the CA private key and X.509 certificate to be in binary DER format
+then just omit the `--outform pem` option. The directory `/etc/swanctl/x509ca`
+contains all required CA certificates either in binary DER or in Base64 PEM
+format. Irrespective of the file suffix the correct format will be determined
+by strongSwan automagically.
+
+
+### Generating a Host or User End Entity Certificate ###
 
-     subjectAltName=DNS:moon.strongswan.org,IP:192.168.0.1
+Again we are using the command
 
-but the use of an IP address for the identification of a host should be
-discouraged anyway.
+    pki --gen --type ed25519 --outform pem > moonKey.pem
 
-For user certificates the appropriate ID type is RFC822_ADDR which can be
-specified as
+to generate an Ed25519 private key for the host `moon`. Alternatively you could
+type
 
-     subjectAltName=email:carol@strongswan.org
+    pki --gen --type rsa --size 3072 > moonKey.der
 
-or if the user's e-mail address is part of the subject's distinguished name
+to generate a traditional 3072 bit RSA key and store it in binary DER format.
+As an alternative a **TPM 2.0** *Trusted Platform Module* available on every
+recent Intel platform could be used as a virtual smartcard to securely store an
+RSA or ECDSA private key. For details, refer to the TPM 2.0
+[HOWTO](https://wiki.strongswan.org/projects/strongswan/wiki/TpmPlugin).
 
-     subjectAltName=email:copy
+In a next step the command
 
-Now the certificate request can be signed by the CA with the command
+    pki --req --type priv --in moonKey.pem \
+              --dn "C=CH, O=strongswan, CN=moon.strongswan.org \
+              --san moon.strongswan.org --outform pem > moonReq.pem
 
-     openssl ca -in hostReq.pem -days 730 -out hostCert.pem -notext
+creates a PKCS#10 certificate request that has to be signed by the CA.
+Through the [multiple] use of the `--san` parameter any number of desired
+*subjectAlternativeNames* can be added to the request. These can be of the
+form
 
-If you omit the -days option then the default_days value (365 days) specified
-in openssl.cnf is used.  The -notext option avoids that a human readable
-listing of the certificate is prepended to the base64 encoded certificate
-body.
+    --san sun.strongswan.org     # fully qualified host name
+    --san carol@strongswan.org   # RFC822 user email address
+    --san 192.168.0.1            # IPv4 address
+    --san fec0::1                # IPv6 address
 
-If you want to use the dynamic CRL fetching feature described in section 4.7
-then you may include one or several crlDistributionPoints in your end
-certificates.  This can be done in the [ usr_cert ] section of the openssl.cnf
-configuration file:
+Based on the certificate request the CA issues a signed end entity certificate
+with the following command
 
-    crlDistributionPoints=@crl_dp
+    pki --issue --cacert strongswanCert.pem --cakey strongswanKey.pem \
+                --type pkcs10 --in moonReq.pem --serial 01 --lifetime 1826 \
+                --outform pem > moonCert.pem
 
-    [ crl_dp ]
+If the `--serial` parameter with a hexadecimal argument is omitted then a random
+serial number is generated. Some third party VPN clients require that a VPN
+gateway certificate contains the *TLS Server Authentication* Extended Key Usage
+(EKU) flag which can be included with the following option
 
-    URI.1="http://crl.strongswan.org/strongswan.crl"
-    URI.2="ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=strongSwan,
-           c=CH?certificateRevocationList"
+    --flag serverAuth
 
-If you have only a single HTTP distribution point then the short form
+If you want to use the dynamic CRL fetching feature described in one of the
+following sections then you may include one or several *crlDistributionPoints*
+in your end entity certificates using the `--crl` parameter
 
-    crlDistributionPoints="URI:http://crl.strongswan.org/strongswan.crl"
+    --crl  http://crl.strongswan.org/strongswan.crl
+    --crl "ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=strongSwan,c=CH?certificateRevocationList"
 
-also works.
+The issued host certificate can be listed with
 
-Again the statements
+    pki --print --in moonCert.pem
 
-    ipsec pki --gen > moonKey.der
-    ipsec pki --pub --in moonKey.der | ipsec pki --issue --lifetime 730 \
-              --cacert strongswanCert.der --cakey strongswanKey.der \
-              --dn "C=CH, O=strongSwan, CN=moon.strongswan.org" \
-              --san moon.strongswan.org --san 192.168.0.1 \
-              --crl http://crl.strongswan.org/strongswan.crl > moonCert.der
+    subject:  "C=CH, O=strongSwan, CN=moon.strongswan.org"
+    issuer:   "C=CH, O=strongSwan, CN=strongSwan Root CA"
+    validity:  not before May 19 10:28:19 2017, ok
+               not after  May 19 10:28:19 2022, ok (expires in 1825 days)
+    serial:    01
+    altNames:  moon.strongswan.org
+    flags:     serverAuth
+    CRL URIs:  http://crl.strongswan.org/strongswan.crl
+    authkeyId: 2b:95:14:5b:c3:22:87:de:d1:42:91:88:63:b3:d5:c1:92:7a:0f:5d
+    subjkeyId: 60:9d:de:30:a6:ca:b9:8e:87:bb:33:23:61:19:18:b8:c4:7e:23:8f
+    pubkey:    ED25519 256 bits
+    keyid:     39:1b:b3:c2:34:72:1a:01:08:40:ce:97:75:b8:be:ce:24:30:26:29
+    subjkey:   60:9d:de:30:a6:ca:b9:8e:87:bb:33:23:61:19:18:b8:c4:7e:23:8f
 
-do something thing similar using the strongSwan PKI tool.
+Usually, a Windows, OSX, Android or iOS based VPN client needs its private key,
+its host or user certificate and the CA certificate.  The most convenient way
+to load this information is to put everything into a PKCS#12 container:
 
-Usually, a Windows or Mac OS X (or iOS) based VPN client needs its private key,
-its host or user certificate, and the CA certificate. The most convenient way
-to load this information is to put everything into a PKCS#12 file:
+    openssl pkcs12 -export -inkey carolKey.pem \
+                   -in carolCert.pem -name "carol" \
+                   -certfile strongswanCert.pem -caname "strongSwan Root CA" \
+                   -out carolCert.p12
 
-     openssl pkcs12 -export -inkey carolKey.pem \
-                    -in carolCert.pem -name "carol" \
-                    -certfile strongswanCert.pem -caname "strongSwan Root CA" \
-                    -out carolCert.p12
+The strongSwan **pki** tool currently is not able to create PKCS#12 containers
+so that **openssl** must be used.
 
 
-3.3 Generating a CRL
-    ----------------
+### Generating a CRL ###
 
 An empty CRL that is signed by the CA can be generated with the command
 
-     openssl ca -gencrl -crldays 15 -out crl.pem
-
-If you omit the -crldays option then the default_crl_days value (30 days)
-specified in openssl.cnf is used.
-
-If you prefer the CRL to be in binary DER format then this conversion
-can be achieved with
-
-     openssl crl -in crl.pem -outform DER -out cert.crl
-
-The strongSwan PKI tool provides the ipsec pki --signcrl command to sign CRLs.
-
-The directory /etc/ipsec.d/crls contains all CRLs either in binary DER
-or in base64 PEM format, irrespective of the file suffix the correct format
-will be determined.
-
-
-3.4 Revoking a certificate
-    ----------------------
-
-A specific host certificate stored in the file host.pem is revoked with the
-command
-
-     openssl ca -revoke host.pem
-
-Next the CRL file must be updated
-
-     openssl ca -gencrl -crldays 60 -out crl.pem
-
-The content of the CRL file can be listed with the command
-
-     openssl crl -in crl.pem -noout -text
-
-in the case of a base64 CRL, or alternatively for a CRL in DER format
-
-     openssl crl -inform DER -in cert.crl -noout -text
-
-Again the ipsec pki --signcrl command may be used to create new CRLs containing
-additional certificates.
-
-
-4. Configuring the connections - ipsec.conf
-   ----------------------------------------
-
-4.1 Configuring my side
-    -------------------
-
-Usually the local side is the same for all connections.  Therefore it makes
-sense to put the definitions characterizing the strongSwan security gateway into
-the conn %default section of the configuration file /etc/ipsec.conf.  If we
-assume throughout this document that the strongSwan security gateway is left and
-the peer is right then we can write
-
-conn %default
-     leftcert=moonCert.pem
-     # load connection definitions automatically
-     auto=add
-
-The X.509 certificate by which the strongSwan security gateway will authenticate
-itself by sending it in binary form to its peers as part of the Internet Key
-Exchange (IKE) is specified in the line
-
-     leftcert=moonCert.pem
-
-The certificate can either be stored in base64 PEM-format or in the binary
-DER-format. Irrespective of the file suffix the correct format will be
-determined.  Therefore
-
-     leftcert=moonCert.der
-
-or
-
-     leftcert=moonCert.cer
-
-would also be valid alternatives.
-
-When using relative pathnames as in the examples above, the certificate files
-must be stored in in the directory /etc/ipsec.d/certs.  In order to distinguish
-strongSwan's own certificates from locally stored trusted peer certificates
-(see section 5.5 for details), they could also be stored in a subdirectory
-below /etc/ipsec.d/certs as e.g. in
-
-    leftcert=mycerts/moonCert.pem
-
-Absolute pathnames are also possible as in
-
-    leftcert=/usr/ssl/certs/moonCert.pem
-
-As an ID for the VPN gateway we recommend the use of a Fully Qualified Domain
-Name (FQDN) of the form
-
-conn rw
-     right=%any
-     leftid=@moon.strongswan.org
-
-Important: When a FQDN identifier is used it must be explicitly included as a
-so called subjectAltName of type dnsName (DNS:) in the certificate indicated
-by leftcert.  For details on how to generate certificates with subjectAltNames,
-please refer to section 3.2.
-
-If you don't want to mess with subjectAltNames, you can use the certificate's
-Distinguished Name (DN) instead, which is an identifier of type DER_ASN1_DN
-and which can be written e.g. in the LDAP-type format
-
-conn rw
-     right=%any
-     leftid="C=CH, O=strongSwan, CN=moon.strongswan.org"
+    pki --signcrl --cacert strongswanCert.pem --cakey strongswanKey.pem \
+                  --lifetime 30 > strongswan.crl
 
-Since the subject's DN is part of the certificate, the leftid does not have to
-be declared explicitly. Thus the entry
+If you omit the `--lifetime` option then the default value of 15 days is used.
+CRLs can either be uploaded to a HTTP or LDAP server or put in binary DER or
+Base64 PEM format into the `/etc/swanctl/x509crl` directory from where they are
+loaded into the **charon** daemon with the command
 
-conn rw
-     right=%any
+    swanctl --load-creds
 
-automatically assumes the subject DN of leftcert to be the host ID.
 
+### Revoking a Certificate ###
 
-4.2 Multiple certificates
-    ---------------------
+A specific end entity certificate is revoked with the command
 
-strongSwan supports multiple local host certificates and corresponding
-RSA private keys:
+    pki --signcrl --cacert strongswanCert.pem --cakey strongswanKey.pem \
+                  --lifetime 30 --lastcrl strongswan.crl \
+                  --reason key-compromise --cert moonCert.pem > new.crl
 
-conn rw1
-     right=%any
-     rightid=@peer1.domain1
-     leftcert=myCert1.pem
-     # leftid is DN of myCert1
-
-conn rw2
-     right=%any
-     rightid=@peer2.domain2
-     leftcert=myCert2.pem
-     # leftid is DN of myCert2
-
-When peer1 initiates a connection then strongSwan will send myCert1 and will
-sign with myKey1 defined in /etc/ipsec.secrets (see section 6.2) whereas
-myCert2 and myKey2 will be used in a connection setup started from peer2.
-
-
-4.3 Configuring the peer side using CA certificates
-    -----------------------------------------------
-
-Now we can proceed to define our connections.  In many applications we might
-have dozens of road warriors connecting to a central strongSwan security
-gateway. The following most simple statement:
-
-conn rw
-     right=%any
-
-defines the general roadwarrior case.  The line right=%any literally means that
-any IPsec peer is accepted, regardless of its current IP source address and its
-ID, as long as the peer presents a valid X.509 certificate signed by a CA the
-strongSwan security gateway puts explicit trust in.  Additionally, the signature
-during IKE gives proof that the peer is in possession of the private RSA key
-matching the public key contained in the transmitted certificate.
-
-The ID by which a peer is identifying itself during IKE can by any of the ID
-types IPV[46]_ADDR, FQDN, RFC822_ADDR or DER_ASN1_DN.  If one of the first
-three ID types is used, then the accompanying X.509 certificate of the peer
-must contain a matching subjectAltName field of the type ipAddress (IP:),
-dnsName (DNS:) or rfc822Name (email:), respectively.  With the fourth type
-DER_ASN1_DN the identifier must completely match the subject field of the
-peer's certificate.  One of the two possible representations of a
-Distinguished Name (DN) is the LDAP-type format
-
-     rightid="C=CH, O=strongSwan IPsec, CN=sun.strongswan.org"
-
-Additional whitespace can be added everywhere as desired since it will be
-automatically eliminated by the X.509 parser.  An exception is the single
-whitespace between individual words, like e.g. in strongSwan IPsec, which is
-preserved by the parser.
-
-The Relative Distinguished Names (RDNs) can alternatively be separated by a
-slash '/' instead of a comma ','
-
-     rightid="/C=CH/O=strongSwan IPsec/CN=sun.strongswan.org"
-
-This is the representation extracted from the certificate by the OpenSSL
-command line option
-
-     openssl x509 -in sunCert.pem -noout -subject
-
-The following RDNs are supported by strongSwan
-
-+-------------------------------------------------------+
-| DC                   Domain Component                 |
-|-------------------------------------------------------|
-| C                    Country                          |
-|-------------------------------------------------------|
-| ST                   State or province                |
-|-------------------------------------------------------|
-| L                    Locality or town                 |
-|-------------------------------------------------------|
-| O                    Organization                     |
-|-------------------------------------------------------|
-| OU                   Organizational Unit              |
-|-------------------------------------------------------|
-| CN                   Common Name                      |
-|-------------------------------------------------------|
-| ND                   NameDistinguisher, used with CN  |
-|-------------------------------------------------------|
-| N                    Name                             |
-|-------------------------------------------------------|
-| G                    Given name                       |
-|-------------------------------------------------------|
-| S                    Surname                          |
-|-------------------------------------------------------|
-| I                    Initials                         |
-|-------------------------------------------------------|
-| T                    Personal title                   |
-|-------------------------------------------------------|
-| E                    E-mail                           |
-|-------------------------------------------------------|
-| Email                E-mail                           |
-|-------------------------------------------------------|
-| emailAddress         E-mail                           |
-|-------------------------------------------------------|
-| SN                   Serial number                    |
-|-------------------------------------------------------|
-| serialNumber         Serial number                    |
-|-------------------------------------------------------|
-| D                    Description                      |
-|-------------------------------------------------------|
-| ID                   X.500 Unique Identifier          |
-|-------------------------------------------------------|
-| UID                  User ID                          |
-|-------------------------------------------------------|
-| TCGID                [Siemens] Trust Center Global ID |
-|-------------------------------------------------------|
-| UN                   Unstructured Name                |
-|-------------------------------------------------------|
-| unstructuredName     Unstructured Name                |
-|-------------------------------------------------------|
-| UA                   Unstructured Address             |
-|-------------------------------------------------------|
-| unstructuredAddress  Unstructured Address             |
-|-------------------------------------------------------|
-| EN                   Employee Number                  |
-|-------------------------------------------------------|
-| employeeNumber       Employee Number                  |
-|-------------------------------------------------------|
-| dnQualifier          DN Qualifier                     |
-+-------------------------------------------------------+
-
-With the roadwarrior connection definition listed above, an IPsec SA for
-the strongSwan security gateway moon.strongswan.org itself can be established.
-If any roadwarrior should be able to reach e.g. the two subnets 10.1.0.0/24
-and 10.1.3.0/24 behind the security gateway then the following connection
-definitions will make this possible
-
-conn rw1
-     right=%any
-     leftsubnet=10.1.0.0/24
-
-conn rw3
-     right=%any
-     leftsubnet=10.1.3.0/24
-
-For IKEv2 connections this can even be simplified by using
-
-    leftsubnet=10.1.0.0/24,10.1.3.0/24
-
-If not all peers in possession of a X.509 certificate signed by a specific
-certificate authority shall be given access to the Linux security gateway,
-then either a subset of them can be barred by listing the serial numbers of
-their certificates in a certificate revocation list (CRL) as specified in
-section 5.2 or as an alternative, access can be controlled by explicitly
-putting a roadwarrior entry for each eligible peer into ipsec.conf:
-
-conn sun
-     right=%any
-     rightid=@sun.strongswan.org
-
-conn carol
-     right=%any
-     rightid=carol@strongswan.org
-
-conn dave
-     right=%any
-     rightid="C=CH, O=strongSwan, CN=dave@strongswan.org"
-
-When the IP address of a peer is known to be stable, it can be specified as
-well.  This entry is mandatory when the strongSwan host wants to act as the
-initiator of an IPsec connection.
-
-conn sun
-     right=192.168.0.2
-     rightid=@sun.strongswan.org
-
-conn carol
-     right=192.168.0.100
-     rightid=carol@strongswan.org
-
-conn dave
-     right=192.168.0.200
-     rightid="C=CH, O=strongSwan, CN=dave@strongswan.org"
-
-conn venus
-     right=192.168.0.50
-
-In the last example the ID types FQDN, RFC822_ADDR, DER_ASN1_DN and IPV4_ADDR,
-respectively, were used.  Of course all connection definitions presented so far
-have included the lines in the conn %defaults section, comprising among other
-a leftcert entry.
-
-
-4.4 Handling Virtual IPs and narrowing
-    ----------------------------------
-
-Often roadwarriors are behind NAT-boxes with IPsec passthrough, which causes
-the inner IP source address of an IPsec tunnel to be different from the
-outer IP source address usually assigned dynamically by the ISP.
-Whereas the varying outer IP address can be handled by the right=%any
-construct, the inner IP address or subnet must always be declared in a
-connection definition. Therefore for the three roadwarriors rw1 to rw3
-connecting to a strongSwan security gateway the following entries are
-required in /etc/ipsec.conf:
-
-conn rw1
-     right=%any
-     righsubnet=10.4.0.5/32
-
-conn rw2
-     right=%any
-     rightsubnet=10.4.0.47/32
-
-conn rw3
-     right=%any
-     rightsubnet=10.4.0.128/28
-
-Because the charon daemon uses narrowing (even for IKEv1) these three entries
-can be reduced to the single connection definition
-
-conn rw
-     right=%any
-     rightsubnet=10.4.0.0/24
-
-Any host will be accepted (of course after successful authentication based on
-the peer's X.509 certificate only) if it declares a client subnet lying totally
-within the brackets defined by the subnet definition (in our example
-10.4.0.0/24).
-
-This strongSwan feature can also be helpful with VPN clients getting a
-dynamically assigned inner IP from a DHCP server located on the NAT router box.
-
-
-4.5 Protocol and Port Selectors
-    ---------------------------
-
-strongSwan offer the possibility to restrict the protocol and optionally the
-ports in an IPsec SA using the rightprotoport and leftprotoport parameters.
-
-Some examples:
-
-conn icmp
-     right=%any
-     rightprotoport=icmp
-     leftid=@moon.strongswan.org
-     leftprotoport=icmp
+Instead of the certificate file (in our example moonCert.pem), the serial number
+of the certificate to be revoked can be indicated using the `--serial`
+parameter. The `pki --signcrl --help` command documents all possible revocation
+reasons but the `--reason` parameter can also be omitted. The content of the new
+CRL file can be listed with the command
 
-conn http
-     right=%any
-     rightprotoport=6
-     leftid=@moon.strongswan.org
-     leftprotoport=6/80
+    pki --print --type crl --in new.crl
 
-conn l2tp       # with port wildcard for Mac OS X Panther interoperability
-     right=%any
-     rightprotoport=17/%any
-     leftid=@moon.strongswan.org
-     leftprotoport=17/1701
+    issuer:   "C=CH, O=strongSwan, CN=strongSwan Root CA"
+    update:    this on May 19 11:13:01 2017, ok
+               next on Jun 18 11:13:01 2017, ok (expires in 29 days)
+    serial:    02
+    authKeyId: 2b:95:14:5b:c3:22:87:de:d1:42:91:88:63:b3:d5:c1:92:7a:0f:5d
+    1 revoked certificate:
+      01: May 19 11:13:01 2017, key compromise
 
-conn dhcp
-     right=%any
-     rightprotoport=udp/bootpc
-     leftid=@moon.strongswan.org
-     leftsubnet=0.0.0.0/0  #allows DHCP discovery broadcast
-     leftprotoport=udp/bootps
-     rekey=no
-     keylife=20s
-     rekeymargin=10s
-     auto=add
 
-Protocols and ports can be designated either by their numerical values
-or by their acronyms defined in /etc/services.
+### Local Caching of CRLs ###
 
-    ipsec status
+The `strongswan.conf` option
 
-shows the following connection definitions:
-
-"icmp": 192.168.0.1[@moon.strongswan.org]:1/0...%any:1/0
-"http": 192.168.0.1[@moon.strongswan.org]:6/80...%any:6/0
-"l2tp": 192.168.0.1[@moon.strongswan.org]:17/1701...%any:17/%any
-"dhcp": 0.0.0.0/0===192.168.0.1[@moon.strongswan.org]:17/67...%any:17/68
-
-Based on the protocol and port selectors appropriate policies will be set
-up, so that only the specified payload types will pass through the IPsec
-tunnel.
-
-
-4.6 IPsec policies based on wildcards
-    ---------------------------------
-
-In large VPN-based remote access networks there is often a requirement that
-access to the various parts of an internal network must be granted selectively,
-e.g. depending on the group membership of the remote access user.  strongSwan
-makes this possible by applying wildcard filtering on the VPN user's
-distinguished name (ID_DER_ASN1_DN).
-
-Let's make a practical example:
-
-An organization has a sales department (OU=Sales) and a research group
-(OU=Research).  In the company intranet there are separate subnets for Sales
-(10.0.0.0/24) and Research (10.0.1.0/24) but both groups share a common web
-server (10.0.2.100).  The VPN clients use Virtual IP addresses that are either
-assigned statically or from a dynamic pool.  The sales and research departments
-use IP addresses from separate address pools (10.1.0.0/24) and (10.1.1.0/24),
-respectively.  An X.509 certificate is issued to each employee, containing in
-its subject distinguished name the country (C=CH), the company (O=ACME),
-the group membership(OU=Sales or OU=Research) and the common name (e.g.
-CN=Bart Simpson).
-
-The IPsec policy defined above can now be enforced with the following three
-IPsec security associations:
-
-conn sales
-     right=%any
-     rightid="C=CH, O=ACME, OU=Sales, CN=*"
-     rightsubnet=10.1.0.0/24         # Sales IP range
-     leftsubnet=10.0.0.0/24          # Sales subnet
-
-conn research
-     right=%any
-     rightid="C=CH, O=ACME, OU=Research, CN=*"
-     rightsubnet=10.1.1.0/24         # Research IP range
-     leftsubnet=10.0.1.0/24          # Research subnet
-
-conn web
-     right=%any
-     rightid="C=CH, O=ACME, OU=*, CN=*"
-     rightsubnet=10.1.0.0/23         # Remote access IP range
-     leftsubnet=10.0.2.100/32        # Web server
-     rightprotoport=tcp              # TCP protocol only
-     leftprotoport=tcp/http          # TCP port 80 only
-
-The '*' character is used as a wildcard in relative distinguished names (RDNs).
-In order to match a wildcard template, the ID_DER_ASN1_DN of a peer must contain
-the same number of RDNs (selected from the list in section 4.3) appearing in the
-exact order defined by the template.
-
-    "C=CH, O=ACME, OU=Research, OU=Special Effects, CN=Bart Simpson"
-
-matches the templates
-
-    "C=CH, O=ACME, OU=Research, OU=*, CN=*"
-
-    "C=CH, O=ACME, OU=*, OU=Special Effects, CN=*"
-
-    "C=CH, O=ACME, OU=*, OU=*, CN=*"
-
-but not the template
-
-    "C=CH, O=ACME, OU=*, CN=*"
-
-which doesn't have the same number of RDNs.
-
-
-4.7 IPsec policies based on CA certificates
-    ---------------------------------------
-
-As an alternative to the wildcard based IPsec policies described in section 4.6,
-access to specific client host and subnets can be controlled on the basis of
-the CA that issued the peer certificate
-
-
-conn sales
-     right=%any
-     rightca="C=CH, O=ACME, OU=Sales, CN=Sales CA"
-     rightsubnet=10.1.0.0/24         # Sales IP range
-     leftsubnet=10.0.0.0/24          # Sales subnet
-
-conn research
-     right=%any
-     rightca="C=CH, O=ACME, OU=Research, CN=Research CA"
-     rightsubnet=10.1.1.0/24         # Research IP range
-     leftsubnet=10.0.1.0/24          # Research subnet
-
-conn web
-     right=%any
-     rightca="C=CH, O=ACME, CN=ACME Root CA"
-     rightsubnet=10.1.0.0/23         # Remote access IP range
-     leftsubnet=10.0.2.100/32        # Web server
-     rightprotoport=tcp              # TCP protocol only
-     leftprotoport=tcp/http          # TCP port 80 only
-
-In the example above, the connection "sales" can be used by peers
-presenting certificates issued by the Sales CA, only.  In the same way,
-the use of the connection "research" is restricted to owners of certificates
-issued by the Research CA.  The connection "web" is open to both "Sales" and
-"Research" peers because the required "ACME Root CA" is the issuer of the
-Research and Sales intermediate CAs.  If no rightca parameter is present
-then any valid certificate issued by one of the trusted CAs in
-/etc/ipsec.d/cacerts can be used by the peer.
-
-The leftca parameter usually doesn't have to be set explicitly because
-by default it is set to the issuer field of the certificate loaded via
-leftcert.  The statement
-
-     rightca=%same
-
-sets the CA requested from the peer to the CA used by the left side itself
-as e.g. in
-
-conn sales
-     right=%any
-     rightca=%same
-     leftcert=mySalesCert.pem
-
-
-5. Configuring certificates and CRLs
-   ---------------------------------
-
-
-5.1 Installing the CA certificates
-    ------------------------------
-
-X.509 certificates received by strongSwan during the IKE protocol are
-automatically authenticated by going up the trust chain until a self-signed
-root CA certificate is reached.  Usually host certificates are directly signed
-by a root CA, but strongSwan also supports multi-level hierarchies with
-intermediate CAs in between.  All CA certificates belonging to a trust chain
-must be copied in either binary DER or base64 PEM format into the directory
-
-     /etc/ipsec.d/cacerts/
-
-
-5.2 Installing optional certificate revocation lists (CRLs)
-    -------------------------------------------------------
-
-By copying a CA certificate into /etc/ipsec.d/cacerts/, automatically all user
-or host certificates issued by this CA are declared valid.  Unfortunately,
-private keys might get compromised inadvertently or intentionally, personal
-certificates of users leaving a company have to be blocked immediately, etc.
-To this purpose certificate revocation lists (CRLs) have been created.  CRLs
-contain the serial numbers of all user or host certificates that have been
-revoked due to various reasons.
-
-After successful verification of the X.509 trust chain, strongSwan searches its
-list of CRLs either obtained by loading them from the /etc/ipsec.d/crls/
-directory or fetching them dynamically from a HTTP or LDAP server for the
-presence of a CRL issued by the CA that has signed the certificate.
-
-If the serial number of the certificate is found in the CRL then the public key
-contained in the certificate is declared invalid and the IPsec SA will not be
-established.  If no CRL is found or if the deadline defined in the nextUpdate
-field of the CRL has been reached, a warning is issued but the public key will
-nevertheless be accepted.  CRLs must be stored either in binary DER or base64
-PEM format in the crls directory.
-
-
-5.3 Dynamic update of certificates and CRLs
-    ---------------------------------------
-
-strongSwan reads certificates and CRLs from their respective files during system
-startup and keeps them in memory.  X.509 certificates have a finite life span
-defined by their validity field.  Therefore it must be possible to replace CA or
-OCSP certificates kept in system memory without disturbing established IKE SAs.
-Certificate revocation lists should also be updated in the regular intervals
-indicated by the nextUpdate field in the CRL body.  The following interactive
-commands allow the manual replacement of the various files:
-
-+---------------------------------------------------------------------------+
-| ipsec rereadsecrets       reload file /etc/ipsec.secrets                  |
-|---------------------------------------------------------------------------|
-| ipsec rereadcacerts       reload all files in /etc/ipsec.d/cacerts/       |
-|---------------------------------------------------------------------------|
-| ipsec rereadaacerts       reload all files in /etc/ipsec.d/aacerts/       |
-|---------------------------------------------------------------------------|
-| ipsec rereadocspcerts     reload all files in /etc/ipsec.d/ocspcerts/     |
-|---------------------------------------------------------------------------|
-| ipsec rereadacerts        reload all files in /etc/ipsec.d/acerts/        |
-|---------------------------------------------------------------------------|
-| ipsec rereadcrls          reload all files in /etc/ipsec.d/crls/          |
-|---------------------------------------------------------------------------|
-| ipsec rereadall           ipsec rereadsecrets                             |
-|                                 rereadcacerts                             |
-|                                 rereadaacerts                             |
-|                                 rereadocspcerts                           |
-|                                 rereadacerts                              |
-|                                 rereadcrls                                |
-|---------------------------------------------------------------------------|
-| ipsec purgeocsp           purge the OCSP cache and fetching requests      |
-+---------------------------------------------------------------------------+
-
-CRLs can also be automatically fetched from an HTTP or LDAP server by using
-the CRL distribution points contained in X.509 certificates.
-
-
-5.4 Local caching of CRLs
-    ---------------------
-
-The the ipsec.conf option
-
-   config setup
-        cachecrls=yes
+    charon {
+        cache_crls = yes
+    }
 
 activates the local caching of CRLs that were dynamically fetched from an
-HTTP or LDAP server.  Cached copies are stored in /etc/ipsec.d/crls using a
-unique filename formed from the issuer's SubjectKeyIdentifier and the
-suffix .crl.
+HTTP or LDAP server.  Cached copies are stored in `/etc/swanctl/x509crl` using a
+unique filename formed from the issuer's *subjectKeyIdentifier* and the
+suffix `.crl`.
 
 With the cached copy the CRL is immediately available after startup.  When the
-local copy is about to expire it is automatically replaced with an updated CRL
-fetched from one of the defined CRL distribution points.
-
-
-5.5 Online Certificate Status Protocol (OCSP)
-    -----------------------------------------
-
-The Online Certificate Status Protocol is defined by RFC 2560.  It can be
-used to query an OCSP server about the current status of an X.509 certificate
-and is often used as a more dynamic alternative to a static Certificate
-Revocation List (CRL).  Both the OCSP request sent by the client and the OCSP
-response messages returned by the server are transported via a standard
-TCP/HTTP connection.  Therefore cURL support must be enabled during
-configuration.
-
-In the simplest OCSP setup, a default URI under which the OCSP server for a
-given CA can be accessed is defined in ipsec.conf:
-
-   ca strongswan
-        cacert=strongswanCert.pem
-        ocspuri=http://ocsp.strongswan.org:8880
-        auto=add
-
-The HTTP port can be freely chosen.
-
-OpenSSL implements an OCSP server that can be used in conjunction with an
-openssl-based Public Key Infrastructure.  The OCSP server is started with the
-following command:
-
-    openssl ocsp -index index.txt -CA strongswanCert.pem -port 8880 \
-                 -rkey ocspKey.pem -rsigner ocspCert.pem \
-                 -resp_no_certs -nmin 60 -text
-
-The command consists of the parameters
-
- -index    index.txt is a copy of the OpenSSL index file containing the list of
-           all issued certificates.  The certificate status in index.txt
-           is designated either by V for valid or R for revoked.  If a new
-           certificate is added or if a certificate is revoked using the
-           openssl ca command, the OCSP server must be restarted in order for
-           the changes in index.txt to take effect.
-
- -CA       the CA certificate
-
- -port     the HTTP port the OCSP server is listening on.
-
- -rkey     the private key used to sign the OCSP response.  The use of the
-           sensitive CA private key is not recommended since this could
-           jeopardize the security of your production PKI if the OCSP
-           server is hacked.  It is much better to generate a special
-           RSA private key just for OCSP signing use instead.
-
- -rsigner  the certificate of the OCSP server containing a public key which
-           matches the private key defined by -rkey and which can be used by
-           the client to check the trustworthiness of the signed OCSP response.
-
- -resp_no_certs  With this option the OCSP signer certificate defined by
-                 -rsigner is not included in the OCSP response.
-
- -nmin     the validity interval of an OCSP response given in minutes.
-
- -text     this option activates a verbose logging output, showing the contents
-           of both the received OCSP request and sent OCSP response.
-
-
-The OCSP signer certificate can either be put into the default directory
-
-    /etc/ipsec.d/ocspcerts
-
-or alternatively strongSwan can receive it as part of the OCSP response from the
-remote OCSP server.  In order to verify that the server is indeed authorized by
-a CA to deal out certificate status information an extended key usage attribute
-must be included in the OCSP server certificate.  Just insert the parameter
-
-    extendedKeyUsage=OCSPSigner
-
-in the [ usr_cert ] section of your openssl.cnf configuration file before
-the CA signs the OCSP server certificate.
-
-For a given CA the corresponding ca section in ipsec.conf (see section 7) allows
-to define the URI of a single OCSP server.  As an alternative an OCSP URI can be
-embedded into each host and user certificate by putting the line
-
-    authorityInfoAccess = OCSP;URI:http://ocsp.strongswan.org:8880
-
-into the [ usr_cert ] section of your openssl.cnf configuration file.
-If an OCSP authorityInfoAccess extension is present in a certificate then this
-record overrides the default URI defined by the ca section.
-
-
-5.6 CRL Policy
-    ----------
-
-By default strongSwan is quite tolerant concerning the handling of CRLs. It is
-not mandatory for a CRL to be present in /etc/ipsec.d/crls and if the expiration
-date defined by the nextUpdate field of a CRL has been reached just a warning
-is issued but a peer certificate will always be accepted if it has not been
-revoked.
-
-If you want to enforce a stricter CRL policy then you can do this by setting
-the "strictcrlpolicy" option.  This is done in the "config setup" section
-of the ipsec.conf file:
-
-    config setup
-         strictcrlpolicy=yes
-          ...
-
-A certificate received from a peer will not be accepted if no corresponding
-CRL or OCSP response is available.  And if an ISAKMP SA re-negotiation takes
-place after the nextUpdate deadline has been reached, the peer certificate
-will be declared invalid and the cached RSA public key will be deleted, causing
-the connection in question to fail.  Therefore if you are going to use the
-"strictcrlpolicy=yes" option, make sure that the CRLs will always be updated
-in time.  Otherwise a total standstill would ensue.
-
-As mentioned earlier the default setting is "strictcrlpolicy=no"
-
-
-5.7 Configuring the peer side using locally stored certificates
-    -----------------------------------------------------------
-
-If you don't want to use trust chains based on CA certificates as proposed in
-section 4.3 you can alternatively import trusted peer certificates directly.
-Thus you do not have to rely on the certificate to be transmitted by the peer
-as part of the IKE protocol.
-
-With the conn %default section defined in section 4.1 and the use of the
-rightcert keyword for the peer side, the connection definitions in section 4.3
-can alternatively be written as
-
-    conn sun
-          right=%any
-          rightid=@sun.strongswan.org
-          rightcert=sunCert.cer
-
-     conn carol
-          right=192.168.0.100
-          rightcert=carolCert.der
-
-If the peer certificates are loaded locally then there is no sense in sending
-any certificates to the other end via the IKE protocol.  Especially if
-self-signed certificates are used which wouldn't be accepted anyway by
-the other side.  In these cases it is recommended to add
-
-    leftsendcert=never
-
-to the connection definition[s] in order to avoid the sending of the host's
-own certificate.  The default value is
-
-    leftsendcert=ifasked
-
-If a peer does not send a certificate request then use the setting
-
-    leftsendcert=always
-
-If a peer certificate contains a subjectAltName extension, then an alternative
-rightid type can be used, as the example "conn sun" shows.  If no rightid
-entry is present then the subject distinguished name contained in the
-certificate is taken as the ID.
-
-Using the same rules concerning pathnames that apply to strongSwan's own
-certificates, the following two definitions are also valid for trusted peer
-certificates:
-
-    rightcert=peercerts/carolCert.der
-
-or
-
-    rightcert=/usr/ssl/certs/carolCert.der
-
-
-6. Configuring the private keys - ipsec.secrets
-   --------------------------------------------
-
-6.1 Loading private key files in PKCS#1 or PKCS#8 format
-    ----------------------------------------------------
-
-Besides strongSwan's raw private key format strongSwan has been enabled to
-load RSA (or ECDSA) private keys in the PKCS#1 or PKCS#8 file format.
-The key files can be optionally secured with a passphrase.
-
-RSA private key files are declared in /etc/ipsec.secrets using the syntax
-
-    : RSA <my keyfile> "<optional passphrase>"
-
-The key file can be either in base64 PEM-format or binary DER-format.  The
-actual coding is detected automatically.  The example
-
-    : RSA moonKey.pem
-
-uses a pathname relative to the default directory
-
-    /etc/ipsec.d/private
-
-As an alternative an absolute pathname can be given as in
-
-    : RSA /usr/ssl/private/moonKey.pem
-
-In both cases make sure that the key files are root readable only.
-
-Often a private key must be transported from the Certification Authority
-where it was generated to the target security gateway where it is going
-to be used.  In order to protect the key it can be encrypted with a symmetric
-cipher using a transport key derived from a cryptographically strong
-passphrase.
-
-Once on the security gateway the private key can either be permanently
-unlocked so that it can be used by Pluto without having to know a
-passphrase
-
-    openssl rsa -in moonKey.pem -out moonKey.pem
-
-or as an option the key file can remain secured.  In this case the passphrase
-unlocking the private key must be added after the pathname in
-/etc/ipsec.secrets
-
-    : RSA moonKey.pem "This is my passphrase"
-
-Some CAs distribute private keys embedded in a PKCS#12 file. Since strongSwan
-is not yet able to read this format directly, the private key part must
-first be extracted using the command
-
-     openssl pkcs12 -nocerts -in moonCert.p12 -out moonKey.pem
-
-if the key file moonKey.pem is to be secured again by a passphrase, or
-
-     openssl pkcs12 -nocerts  -nodes -in moonCert.p12 -out moonKey.pem
-
-if the private key is to be stored unlocked.
-
-
-6.2 Entering passphrases interactively
-    ----------------------------------
-
-On a VPN gateway you would want to put the passphrase protecting the private
-key file right into /etc/ipsec.secrets as described in the previous paragraph,
-so that the gateway can be booted in unattended mode.  The risk of keeping
-unencrypted secrets on a server can be minimized by putting the box into a
-locked room.  As long as no one can get root access on the machine the private
-keys are safe.
-
-On a mobile laptop computer the situation is quite different.  The computer can
-be stolen or the user is leaving it unattended so that unauthorized persons
-can get access to it.  In theses cases it would be preferable not to keep any
-passphrases openly in /etc/ipsec.secrets but to prompt for them interactively
-instead.  This is easily done by defining
-
-    : RSA moonKey.pem %prompt
-
-Since strongSwan is usually started during the boot process, usually no
-interactive console windows is available which can be used to prompt for
-the passphrase.  This must be initiated by the user by typing
-
-    ipsec secrets
-
-which actually is an alias for the existing command
-
-    ipsec rereadsecrets
-
-and which causes a passphrase prompt to appear.  To abort entering a passphrase
-enter just a carriage return.
-
-
-6.3 Multiple private keys
-    ---------------------
-
-strongSwan supports multiple private keys. Since the connections defined
-in ipsec.conf can find the correct private key based on the public key
-contained in the certificate assigned by leftcert, default private key
-definitions without specific IDs can be used
-
-    : RSA myKey1.pem "<optional passphrase1>"
-
-    : RSA myKey2.pem "<optional passphrase2>"
-
-
-7. Configuring CA properties - ipsec.conf
-   --------------------------------------
-
-Besides the definition of IPsec connections the ipsec.conf file can also
-be used to configure a few properties of the certification authorities
-needed to establish the X.509 trust chains.  The following example shows
-some of the parameters that are currently available:
-
-    ca strongswan
-       cacert=strongswanCert.pem
-       ocspuri=http://ocsp.strongswan.org:8880
-       crluri=http://crl.strongswan.org/strongswan.crl'
-       crluri2="ldap://ldap.strongswan.org/O=strongSwan, C=CH?certificateRevocationList"
-       auto=add
-
-In a similar way as conn sections are used for connection definitions, an
-arbitrary number of optional ca sections define the basic properties of CAs.
-
-Each ca section is named with a unique label
-
-       ca strongswan
-
-The only mandatory parameter is
-
-       cacert=strongswanCert.pem
-
-which points to the CA certificate which usually resides in the default
-directory /etc/ipsec.d/cacerts/ but could also be retrieved via an absolute
-path name.
-
-The OCSP URI
-
-       ocspuri=http://ocsp.strongswan.org:8880
-
-allows to define an individual OCSP server per CA.  Also up to two additional
-CRL distribution points (CDPs) can be defined
-
-       crluri=http://crl.strongswan.org/strongswan.crl'
-       crluri2="ldap://ldap.strongswan.org/O=strongSwan, C=CH?certificateRevocationList"
-
-which are added to any CDPs already present in the received certificates
-themselves.
-
-With the auto=add statement the ca definition is automatically loaded during
-startup.  Setting auto=ignore will ignore the ca section.
-
-Any parameters which appear in several ca definitions can be put in
-a common ca %default section
-
-    ca %default
-       crluri=http://crl.strongswan.org/strongswan.crl'
-
-
-8. Monitoring functions
-   --------------------
-
-strongSwan offers the following monitoring functions:
-
-The command
-
-    ipsec listalgs
-
-lists all IKE cryptographic algorithms that are currently
-registered with strongSwan.
-
-
-The command
-
-    ipsec listcerts [--utc]
-
-lists all local certificates, both strongSwan's own and those of
-trusted peer loaded via leftcert and rightcert, respectively.
-
-
-The command
-
-    ipsec listcacerts [--utc]
-
-lists all CA certificates that have been either been loaded from the directory
-/etc/ipsec.d/cacerts/ or received via the IKE protocol.
-
-
-The command
-
-    ipsec listaacerts [--utc]
-
-lists all Authorization Authority certificates that have been loaded from
-the directory /etc/ipsec.d/aacerts/.
-
-
-The command
-
-    ipsec listocspcerts [--utc]
-
-lists all OCSO signer certificates that have been either loaded from
-/etc/ipsec.d/ocspcerts/ or have been received included in the OCSP server
-response.
-
-
-The command
-
-    ipsec listacerts [--utc]
-
-lists all X.509 attribute certificates that have been loaded from the directory
-/etc/ipsec.d/acerts/.
-
-
-The command
-
-    ipsec listcainfos [--utc]
-
-lists the properties defined by the ca definition sections in ipsec.conf.
-
-
-The command
-
-    ipsec listcrls [--utc]
-
-lists all CRLs that have been loaded from /etc/ipsec.d/crls/.
-
-
-The command
-
-
-    ipsec listocsp [--utc]
-
-lists the contents of the OCSP response cache.
-
-
-The command
-
-    ipsec listall [--utc]
-
-is equivalent to using all of the above commands.
-
-
-9. Firewall support functions
-   --------------------------
-
-
-9.1 Environment variables in the updown script
-    ------------------------------------------
-
-strongSwan makes the following environment variables available
-in the updown script indicated by the leftupdown option:
-
-+-------------------------------------------------------------------+
-| Variable               Example                    Comment         |
-|-------------------------------------------------------------------|
-| $PLUTO_PEER_ID         carol@strongswan.org       RFC822_ADDR (1) |
-|-------------------------------------------------------------------|
-| $PLUTO_PEER_PROTOCOL   17                         udp         (2) |
-|-------------------------------------------------------------------|
-| $PLUTO_PEER_PORT       68                         bootpc      (3) |
-|-------------------------------------------------------------------|
-| $PLUTO_PEER_CA         C=CH, O=ACME, CN=Sales CA              (4) |
-|-------------------------------------------------------------------|
-| $PLUTO_MY_ID           @moon.strongswan.org       FQDN        (1) |
-|-------------------------------------------------------------------|
-| $PLUTO_MY_PROTOCOL     17                         udp         (2) |
-|-------------------------------------------------------------------|
-| $PLUTO_MY_PORT         67                         bootps      (3) |
-+-------------------------------------------------------------------+
-
-(1) $PLUTO_PEER_ID/$PLUTO_MY_ID contain the IDs of the two ends
-    of an established connection. In our examples these
-    correspond to the strings defined by rightid and leftid,
-    respectively.
-
-(2) $PLUTO_PEER_PROTOCOL/$PLUTO_MY_PROTOCOL contain the protocol
-    defined by the rightprotoport and leftprotoport options,
-    respectively. Both variables contain the same protocol value.
-    The variables take on the value '0' if no protocol has been defined.
-
-(3) $PLUTO_PEER_PORT/$PLUTO_MY_PORT contain the ports defined by
-    the rightprotoport and leftprotoport options, respectively.
-    The variables take on the value '0' if no port has been defined.
-
-(4) $PLUTO_PEER_CA contains the distinguished name of the CA that
-    issued the peer's certificate.
-
-There are several more, refer to the provided default script for a documentation
-of these.
-
-
-9.2 Automatic insertion and deletion of iptables firewall rules
-    -----------------------------------------------------------
-
-The default _updown script automatically inserts and deletes dynamic iptables
-firewall rules upon the establishment or teardown, respectively, of an IPsec
-security association.  This feature is activated with the line
-
-   leftfirewall=yes
-
-If you define a local client subnet with a netmask larger than /32 behind
-the gateway then the automatically inserted FORWARD iptables rules will
-not allow to access the internal IP address of the host although it is
-part of the client subnet definition.  If you want additional INPUT and
-OUTPUT iptables rules to be inserted, so that the host itself can be accessed
-then add the following line:
-
-   lefthostaccess=yes
-
-The _updown script also features a logging facility which will register the
-creation (+) and the expiration (-) of each successfully established VPN
-connection in a special syslog file in the following concise and easily
-readable format:
-
-Jul 19 18:58:38 moon vpn:
-    + @carol.strongswan.org  192.168.0.100 -- 192.168.0.1 == 10.1.0.0/16
-Jul 19 22:15:17 moon vpn:
-    - @carol.strongswan.org  192.168.0.100 -- 192.168.0.1 == 10.1.0.0/16
+local copy has become stale, an updated CRL is automatically fetched from one of
+the defined CRL distribution points during the next IKEv2 authentication.