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).
+information consult the man pages and [**our wiki**](https://wiki.strongswan.org).
## Quickstart ##
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
+ openssl x509 -in strongswanCert.pem -outform DER -out strongswanCert.der
The statements
The OpenSSL statement
- openssl req -newkey rsa:2048 -keyout hostKey.pem \
- -out hostReq.pem
+ 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.
edit the OpenSSL configuration file `openssl.cnf` and add the following line in
the `[ usr_cert ]` section:
- subjectAltName=DNS:moon.strongswan.org
+ 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
+ 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
+ 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
+ subjectAltName=email:carol@strongswan.org
or if the user's e-mail address is part of the subject's distinguished name
- subjectAltName=email:copy
+ 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
+ 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
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
### 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
+ 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
+ openssl crl -in crl.pem -outform DER -out cert.crl
The strongSwan PKI tool provides the `--signcrl` command to sign CRLs.
A specific host certificate stored in the file `host.pem` is revoked with the
command
- openssl ca -revoke host.pem
+ openssl ca -revoke host.pem
Next the CRL file must be updated
- openssl ca -gencrl -crldays 60 -out crl.pem
+ 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
+ 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
+ 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.
and the peer is **right** then we can write
conn %default
- leftcert=moonCert.pem
- # load connection definitions automatically
- auto=add
+ 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
+ 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
Name (FQDN) of the form
conn rw
- right=%any
- leftid=moon.strongswan.org
+ 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
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"
+ 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
+ right=%any
automatically assumes the subject DN of `leftcert` to be the host ID.
RSA private keys:
conn rw1
- right=%any
- rightid=peer1.domain1
- leftcert=myCert1.pem
- # leftid is DN of myCert1
+ 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
+ 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
gateway. The following most simple statement:
conn rw
- right=%any
+ 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
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"
+ 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
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"
+ 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
+ openssl x509 -in sunCert.pem -noout -subject
The following RDNs are supported by strongSwan
definitions will make this possible
conn rw1
- right=%any
- leftsubnet=10.1.0.0/24
+ right=%any
+ leftsubnet=10.1.0.0/24
conn rw3
- right=%any
- leftsubnet=10.1.3.0/24
+ right=%any
+ leftsubnet=10.1.3.0/24
For IKEv2 connections this can even be simplified by using
eligible peer into `ipsec.conf`:
conn sun
- right=%any
- rightid=sun.strongswan.org
+ right=%any
+ rightid=sun.strongswan.org
conn carol
- right=%any
- rightid=carol@strongswan.org
+ right=%any
+ rightid=carol@strongswan.org
conn dave
- right=%any
- rightid="C=CH, O=strongSwan, CN=dave@strongswan.org"
+ 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
+ right=192.168.0.2
+ rightid=sun.strongswan.org
conn carol
- right=192.168.0.100
- rightid=carol@strongswan.org
+ 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"
+ right=192.168.0.200
+ rightid="C=CH, O=strongSwan, CN=dave@strongswan.org"
conn venus
- right=192.168.0.50
+ 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
following entries are required in `/etc/ipsec.conf`:
conn rw1
- right=%any
- righsubnet=10.4.0.5/32
+ right=%any
+ rightsubnet=10.4.0.5/32
conn rw2
- right=%any
- rightsubnet=10.4.0.47/32
+ right=%any
+ rightsubnet=10.4.0.47/32
conn rw3
- right=%any
- rightsubnet=10.4.0.128/28
+ 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
+ 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
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
+ right=%any
+ rightsourceip=10.5.0.0/24
### Protocol and Port Selectors ###
Some examples:
conn icmp
- right=%any
- rightprotoport=icmp
- leftid=moon.strongswan.org
- leftprotoport=icmp
+ right=%any
+ rightprotoport=icmp
+ leftid=moon.strongswan.org
+ leftprotoport=icmp
conn http
- right=%any
- rightprotoport=6
- leftid=moon.strongswan.org
- leftprotoport=6/80
+ 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
+ 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
+ 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`.
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
+ 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
+ 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
+ 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
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
+ 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
+ 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
+ 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,
by default it is set to the issuer field of the certificate loaded via
`leftcert`. The statement
- rightca=%same
+ 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
+ right=%any
+ rightca=%same
+ leftcert=mySalesCert.pem
## Configuring certificates and CRLs ##
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/
+ /etc/ipsec.d/cacerts/
### Installing optional certificate revocation lists (CRLs) ###
The `ipsec.conf` option
config setup
- cachecrls=yes
+ 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
given CA can be accessed is defined in `ipsec.conf`:
ca strongswan
- cacert=strongswanCert.pem
- ocspuri=http://ocsp.strongswan.org:8880
- auto=add
+ cacert=strongswanCert.pem
+ ocspuri=http://ocsp.strongswan.org:8880
+ auto=add
The HTTP port can be freely chosen.
of the `ipsec.conf` file:
config setup
- strictcrlpolicy=yes
- ...
+ 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
alternatively be written as
conn sun
- right=%any
- rightid=sun.strongswan.org
- rightcert=sunCert.cer
+ right=%any
+ rightid=sun.strongswan.org
+ rightcert=sunCert.cer
- conn carol
- right=192.168.0.100
- rightcert=carolCert.der
+ 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
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
+can get access to it. In these 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