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