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
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
| 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.
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
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.
--- /dev/null
+# strongSwan Configuration #
+
+## Overview ##
+
+strongSwan is an OpenSource IPsec-based VPN solution.
+
+This document is just a short introduction of the **ipsec** command which uses
+the legacy **stroke** configuration interface. The current **swanctl** command
+using the modern [**vici**](src/libcharon/plugins/vici/README.md) *Versatile IKE
+Configuration Interface* is described [**here**](README.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.
+
+
+### 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_:
+
+ /etc/ipsec.d/cacerts/strongswanCert.pem
+
+ /etc/ipsec.d/certs/moonCert.pem
+
+ /etc/ipsec.secrets:
+
+ : RSA moonKey.pem "<optional passphrase>"
+
+ /etc/ipsec.conf:
+
+ 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
+
+Configuration on gateway _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 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
+
+
+### 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
+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
+
+
+### 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.
+
+ 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
+
+
+### 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-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
+
+
+## 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.
+
+
+### 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.
+
+
+### Generating a host or user certificate ###
+
+The OpenSSL statement
+
+ 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.
+
+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:
+
+ subjectAltName=DNS:moon.strongswan.org
+
+if you want to identify the host by its Fully Qualified Domain Name (FQDN), or
+
+ subjectAltName=IP:192.168.0.1
+
+if you want the ID to be of type _IPV4_ADDR_. Of course you could include both
+ID types with
+
+ subjectAltName=DNS:moon.strongswan.org,IP:192.168.0.1
+
+but the use of an IP address for the identification of a host should be
+discouraged anyway.
+
+For user certificates the appropriate ID type is _RFC822_ADDR_ which can be
+specified as
+
+ subjectAltName=email:carol@strongswan.org
+
+or if the user's e-mail address is part of the subject's distinguished name
+
+ subjectAltName=email:copy
+
+Now the certificate request can be signed by the CA with the command
+
+ openssl ca -in hostReq.pem -days 730 -out hostCert.pem -notext
+
+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.
+
+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:
+
+ crlDistributionPoints=@crl_dp
+
+ [ crl_dp ]
+
+ URI.1="http://crl.strongswan.org/strongswan.crl"
+ URI.2="ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=strongSwan,
+ c=CH?certificateRevocationList"
+
+If you have only a single HTTP distribution point then the short form
+
+ crlDistributionPoints="URI:http://crl.strongswan.org/strongswan.crl"
+
+also works.
+
+Again the statements
+
+ 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
+
+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
+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
+
+
+### 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) ###
+
+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 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.
+
+
+### 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:
+
+
+| 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 |
+
+
+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 ###
+
+The `ipsec.conf` option
+
+ config setup
+ cachecrls=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`.
+
+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
projects / people / ms / strongswan.git / commitdiff
