README: Converted to swanctl configuration scheme

1 files changed, 541 insertions, 1146 deletions

diff --git a/README.md b/README.md
index e344424d4..979b0eb12 100644
--- a/README.md
+++ b/README.md
@@ -4,23 +4,26 @@
 
 strongSwan is an OpenSource IPsec-based VPN solution.
 
-This document is just a short introduction, for more detailed information
-consult the man pages and [**our wiki**](http://wiki.strongswan.org).
+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).
 
 
 ## 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 one of the sections below.
-The CA certificate `strongswanCert.pem` must be present on all VPN endpoints
-in order to be able to authenticate the peers.
+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.
 
 
-### Site-to-site case ###
+### 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
@@ -31,46 +34,80 @@ set up between the two gateways:
 
 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/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/priv/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
+                   }
+                }
+            }
+        }
 
-    /etc/ipsec.conf:
+Configuration on gateway _sun_:
 
-        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
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/sunCert.pem
+    /etc/swanctl/priv/sunKey.pem
 
-Configuration on gateway _sun_:
+    /etc/swanctl/swanctl.conf:
 
-    /etc/ipsec.d/cacerts/strongswanCert.pem
+        connections {
+            net-net {
+                remote_addrs = 192.168.0.1
 
-    /etc/ipsec.d/certs/sunCert.pem
+                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
+                   }
+                }
+            }
+        }
 
-    /etc/ipsec.secrets:
+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
 
-        : RSA sunKey.pem "<optional passphrase>"
+    swanctl --load-creds
 
-    /etc/ipsec.conf:
+whereas
 
-        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
+    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 ###
+### 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
@@ -79,44 +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 _moon_:
+
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/priv/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/ipsec.d/cacerts/strongswanCert.pem
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/sunCert.pem
+    /etc/swanctl/priv/sunKey.pem
 
-    /etc/ipsec.d/certs/sunCert.pem
+    /etc/swanctl/swanctl.conf:
 
-    /etc/ipsec.secrets:
+        connections {
+            host-host {
+                remote_addrs = 192.168.0.1
 
-        : RSA sunKey.pem "<optional passphrase>"
+                local {
+                    auth = pubkey
+                    certs = sunCert.pem
+                }
+                remote {
+                    auth = pubkey
+                    id = "C=CH, O=strongSwan, CN=moon.strongswan.org"
+                }
+                children {
+                    host-host {
+                        start_action = trap
+                   }
+                }
+            }
+        }
 
-    /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
-
-
-### Roadwarrior case ###
+### 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.
@@ -126,43 +183,68 @@ number of remote VPN clients usually having dynamic IP addresses.
 
 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
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/priv/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/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
-
-
-### Roadwarrior case with virtual IP ###
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/carolCert.pem
+    /etc/swanctl/priv/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
@@ -173,1126 +255,439 @@ an inner IP address chosen from a pre-defined pool.
       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
+`10.3.0.0/16` which can be configured by adding the section
 
-    rightsourceip=10.3.0.0/16
+    pools {
+        rw_pool {
+            addrs = 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
+to the gateway's `swanctl.conf` from where they are loaded into the **charon**
+daemon using the command
 
-    leftsourceip=%config
-
-Configuration on gateway _moon_:
+    swanctl --load-pools
 
-    /etc/ipsec.d/cacerts/strongswanCert.pem
+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
 
-    /etc/ipsec.d/certs/moonCert.pem
+    vips = 0.0.0.0
 
-    /etc/ipsec.secrets:
-
-        : RSA moonKey.pem "<optional passphrase>"
-
-    /etc/ipsec.conf:
+Configuration on gateway _moon_:
 
-        conn rw
-            leftsubnet=10.1.0.0/16
-            leftcert=moonCert.pem
-            right=%any
-            rightsourceip=10.3.0.0/16
-            auto=add
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/rsa/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/ipsec.d/cacerts/strongswanCert.pem
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/carolCert.pem
+    /etc/swanctl/priv/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 ###
 
-    /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
-
-
-## Generating certificates and CRLs ##
+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*.
 
-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.
+    10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
+      moon-net          moon              carol
 
+Configuration on gateway _moon_:
 
-### Generating a CA certificate ###
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/priv/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
+           }
+       }
 
-The OpenSSL statement
+Configuration on roadwarrior _carol_:
 
-    openssl req -x509 -days 1460 -newkey rsa:4096 \
-                -keyout strongswanKey.pem -out strongswanCert.pem
+    /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.
 
-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).
+    10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
+      moon-net          moon              carol
 
-    openssl x509 -in cert.pem -noout -text
+Configuration on gateway _moon_:
 
-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.
+    /etc/swanctl/x509ca/strongswanCert.pem
+    /etc/swanctl/x509/moonCert.pem
+    /etc/swanctl/priv/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
+           }
+       }
 
-If you prefer the CA certificate to be in binary DER format then the following
-command achieves this transformation:
+Configuration on roadwarrior _carol_:
 
-     openssl x509 -in strongswanCert.pem -outform DER -out strongswanCert.der
+    /etc/swanctl/x509ca/strongswanCert.pem
 
-The statements
+    /etc/swanctl/swanctl.conf:
 
-    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
+         connections {
+            home {
+                remote_addrs = moon.strongswan.org
 
-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.
+                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
+                    }
+                }
+            }
+        }
 
-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.
+       secrets {
+           eap-carol {
+               id = carol
+               secret = Ar3etTnp
+           }
+       }
 
 
-### Generating a host or user certificate ###
+## Generating Certificates and CRLs ##
 
-The OpenSSL statement
+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.
 
-     openssl req -newkey rsa:2048 -keyout hostKey.pem \
-                 -out hostReq.pem
 
-generates a 2048 bit RSA private key `hostKey.pem` and a certificate request
-`hostReq.pem` which has to be signed by the CA.
+### Generating a CA Certificate ###
 
-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:
+The pki statement
 
-     subjectAltName=DNS:moon.strongswan.org
+    pki --gen --type ed25519 --outform pem > strongswanKey.pem
 
-if you want to identify the host by its Fully Qualified Domain Name (FQDN), or
+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)
 
-     subjectAltName=IP:192.168.0.1
+    pki --self --ca --lifetime 3652 --in strongswanKey.pem \
+               --dn "C=CH, O=strongSwan, CN=strongSwan Root CA" \
+               --outform pem > strongswanCert.pem
 
-if you want the ID to be of type _IPV4_ADDR_. Of course you could include both
-ID types with
+which can be listed with the command
 
-     subjectAltName=DNS:moon.strongswan.org,IP:192.168.0.1
+    pki --print --in strongswanCert.pem
 
-but the use of an IP address for the identification of a host should be
-discouraged anyway.
+    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
 
-For user certificates the appropriate ID type is _RFC822_ADDR_ which can be
-specified as
+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.
 
-     subjectAltName=email:carol@strongswan.org
 
-or if the user's e-mail address is part of the subject's distinguished name
+### Generating a Host or User End Entity Certificate ###
 
-     subjectAltName=email:copy
+Again we are using the command
 
-Now the certificate request can be signed by the CA with the command
+    pki --gen --type ed25519 --outform pem > moonKey.pem
 
-     openssl ca -in hostReq.pem -days 730 -out hostCert.pem -notext
+to generate an Ed25519 private key for the host `moon`. Alternatively you could
+type
 
-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.
+    pki --gen --type rsa --size 3072 > moonKey.der
 
-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 certificates.  This can be done in the `[ usr_cert ]` section of the
-`openssl.cnf` configuration file:
+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).
 
-    crlDistributionPoints=@crl_dp
+In a next step the command
 
-    [ crl_dp ]
+    pki --req --type priv --in moonKey.pem \
+              --dn "C=CH, O=strongswan, CN=moon.strongswan.org \
+              --san moon.strongswan.org -- outform pem > moonReq.pem
 
-    URI.1="http://crl.strongswan.org/strongswan.crl"
-    URI.2="ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=strongSwan,
-           c=CH?certificateRevocationList"
+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 have only a single HTTP distribution point then the short form
+    --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
 
-    crlDistributionPoints="URI:http://crl.strongswan.org/strongswan.crl"
+Based on the certificate request the CA issues a signed end entity certificate
+with the following command
 
-also works.
+    pki --issue --cacert strongswanCert.pem --cakey strongswanKey.pem \
+                --type pkcs10 --in moonReq.pem --serial 01 --lifetime 1826 \
+                --outform pem > moonCert.pem
 
-Again the statements
+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
 
-    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
+    --flag serverAuth
 
-do something similar using the strongSwan PKI tool.
-
-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
+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
+
+    --crl  http://crl.strongswan.org/strongswan.crl
+    --crl "ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=strongSwan,c=CH?certificateRevocationList"
+
+The issued host certificate can be listed with
+
+    pki --print --in moonCert.pem
+
+    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
+
+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:
 
-     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.
 
 
 ### 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 `--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.
-
-
-### 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 `--signcrl` command of the strongSwan PKI tool may also be used to
-create new CRLs containing additional certificates.
-
-
-## Configuring the connections - ipsec.conf ##
-
-### 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 below 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 the sections above.
-
-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"
-
-Since the subject's DN is part of the certificate, the `leftid` does not have to
-be declared explicitly. Thus the entry
-
-    conn rw
-         right=%any
-
-automatically assumes the subject DN of `leftcert` to be the host ID.
-
-
-### Multiple certificates ###
-
-strongSwan supports multiple local host certificates and corresponding
-RSA private keys:
-
-    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 below) whereas
-_myCert2_ and _myKey2_ will be used in a connection setup started from _peer2_.
-
-
-### 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
-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 parser.  An exception is the single whitespace
-between individual words, like e.g. in `strongSwan IPsec`, which is preserved.
-
-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
-`-subject` command line option
-
-     openssl x509 -in sunCert.pem -noout -subject
-
-The following RDNs are supported by strongSwan
-
-| Name               | Description                      |
-|--------------------|----------------------------------|
-| 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 the roadwarriors 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) 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.
-
-
-### Handling Virtual IPs and narrowing ###
-
-Often roadwarriors are behind NAT-boxes, 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 boundaries 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.
-
-Since the private IP address of roadwarriors will often not be known they are
-usually assigned virtual IPs from a predefined pool.  This also makes routing
-traffic back to the roadwarriors easier. For example, to assign each client an
-IP address from the `10.5.0.0/24` subnet `conn rw` can be defined as
-
-    conn rw
-         right=%any
-         rightsourceip=10.5.0.0/24
-
-
-### Protocol and Port Selectors ###
-
-strongSwan offers the possibility to restrict the protocol and optionally the
-ports in an IPsec SA using the `rightprotoport` and `leftprotoport` parameters.
-For IKEv2 multiple such restrictions can also be configured in
-`leftsubnet` and `rightsubnet`.
-
-Some examples:
-
-    conn icmp
-         right=%any
-         rightprotoport=icmp
-         leftid=moon.strongswan.org
-         leftprotoport=icmp
-
-    conn http
-         right=%any
-         rightprotoport=6
-         leftid=moon.strongswan.org
-         leftprotoport=6/80
-
-    conn l2tp
-         right=%any
-         # with port wildcard for interoperability with certain L2TP clients
-         rightprotoport=17/%any
-         leftid=moon.strongswan.org
-         leftprotoport=17/1701
-
-    conn dhcp
-         right=%any
-         rightprotoport=udp/bootpc
-         leftid=moon.strongswan.org
-         leftsubnet=0.0.0.0/0  #allows DHCP discovery broadcast
-         leftprotoport=udp/bootps
-
-Protocols and ports can be designated either by their numerical values
-or by their acronyms defined in `/etc/services`.
-
-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.
-
-
-### 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=*"
-         rightsourceip=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=*"
-         rightsourceip=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 given earlier) 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.
-
-
-### IPsec policies based on CA certificates ###
-
-As an alternative to the wildcard based IPsec policies described above, 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"
-         rightsourceip=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"
-         rightsourceip=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
-
-
-## Configuring certificates and CRLs ##
-
-
-### 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/
-
-
-### Installing optional certificate revocation lists (CRLs) ###
+    pki --signcrl --cacert strongswanCert.pem --cakey strongswanKey.pem \
+                  --lifetime 30 > strongswan.crl
 
-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.
+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
 
-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.
+    swanctl --load-creds
 
-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 IKE 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 (this behavior can be changed, see below).  CRLs must
-be stored either in binary DER or Base64 PEM format in the `crls` directory.
 
+### Revoking a Certificate ###
 
-### Dynamic update of certificates and CRLs ###
+A specific end entity certificate is revoked with the command
 
-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:
+    pki --signcrl --cacert strongswanCert.pem --cakey strongswanKey.pem \
+                  --lifetime 30 --lastcrl strongswan.crl \
+                  --reason key-compromise --cert moonCert.pem > new.crl
 
+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
 
-| Command                 | Action                                          |
-|-------------------------|-------------------------------------------------|
-| ipsec rereadaacerts     | reload all files in `/etc/ipsec.d/aacerts/`     |
-| ipsec rereadacerts      | reload all files in `/etc/ipsec.d/acerts/`      |
-| ipsec rereadcacerts     | reload all files in `/etc/ipsec.d/cacerts/`     |
-| ipsec rereadcrls        | reload all files in `/etc/ipsec.d/crls/`        |
-| ipsec rereadocspcerts   | reload all files in `/etc/ipsec.d/ocspcerts/`   |
-| ipsec rereadsecrets     | reload `/etc/ipsec.secrets` and configured keys |
-| ipsec rereadall         | all the commands above combined                 |
-| ipsec purgecerts        | purge all cached certificates                   |
-| ipsec purgecrl          | purge all cached CRLs                           |
-| ipsec purgeocsp         | purge the OCSP cache                            |
+    pki --print --type crl --in new.crl
 
+    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
 
-CRLs can also be automatically fetched from an HTTP or LDAP server by using
-the CRL distribution points contained in X.509 certificates.
 
+### Local Caching of CRLs ###
 
-### Local caching of CRLs ###
+The `strongswan.conf` option
 
-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
+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.
-
-
-### 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.
-
-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 below) 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.
-
-
-### 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 IKE SA re-negotiation takes
-place after the _nextUpdate_ deadline has been reached, the peer certificate
-will be declared invalid and the cached 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 might ensue.
-
-As mentioned earlier the default setting is `strictcrlpolicy=no`.
-
-
-### Configuring the peer side using locally stored certificates ###
-
-If you don't want to use trust chains based on CA certificates as proposed above
-you can alternatively import trusted peer certificates directly.
-
-With the `conn %default` section defined above and the use of the `rightcert`
-keyword for the peer side, the connection definitions presented earlier 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 need to send 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
-
-which causes certificates to only be sent if a certificate request is received.
-If a peer does not send a certificate request then the setting
-
-    leftsendcert=always
-
-may be used to force sending of the certificate to the other peer.
-
-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 the gateway'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
-
-
-## Configuring the private keys - ipsec.secrets ##
-
-
-### Loading private key files ###
-
-strongSwan is able to load RSA (or ECDSA) private keys in the PKCS#1 or PKCS#8
-file formats, or from PKCS#12 containers. The key files can optionally be
-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 the IKE daemon 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. strongSwan can read
-private keys directly from such a file (end-entity and CA certificates are
-also extracted):
-
-    : P12 moonCert.p12 "This is my passphrase"
-
-
-### 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 section,
-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 may leave 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.
-
-
-## 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'
-
-
-## Monitoring functions ##
-
-strongSwan offers the following monitoring functions:
-
-| Command             | Action                                            |
-|---------------------|---------------------------------------------------|
-| ipsec listaacerts   | list all Authorization Authority certificates loaded from `/etc/ipsec.d/aacerts/` |
-| ipsec listacerts    | list all X.509 attribute certificates loaded from `/etc/ipsec.d/acerts/` |
-| ipsec listalgs      | list cryptographic algorithms for IKE             |
-| ipsec listcacerts   | list all CA certificates loaded from `/etc/ipsec.d/cacerts/` or received via IKE |
-| ipsec listcainfos   | list all properties defined in `ca` sections in `ipsec.conf` |
-| ipsec listcerts     | list all certificates loaded via `leftcert` and `rightcert` |
-| ipsec listcounters  | list global or connection specific counter values |
-| ipsec listcrls      | list all CLRs loaded from `/etc/ipsec.d/crls/`    |
-| ipsec listocsp      | list contents of the OCSP response cache          |
-| ipsec listocspcerts | list all OCSP signer certificates loaded from `/etc/ipsec.d/ocspcerts/` or received in OCSP responses |
-| ipsec listplugins   | list all loaded plugin features                   |
-| ipsec listpubkeys   | list all raw public keys e.g. loaded via `leftsigkey` and `rightsigkey` |
-| ipsec listall       | all the above commands combined                   |
-| ipsec status        | list concise status information on established connections |
-| ipsec statusall     | list detailed status information on connections |
-
-
-## Firewall support functions ##
-
-
-### 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_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.
-
-There are several more, refer to the provided default script for a documentation
-of them.
-
-
-### 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 `leftsubnet` with a netmask larger than `/32` then the
-automatically inserted _FORWARD_ `iptables` rules will not allow clients to
-access the internal IP address of the gateway even if it is part of that 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.