1: # strongSwan Configuration #
2:
3: ## Overview ##
4:
5: strongSwan is an OpenSource IPsec-based VPN solution.
6:
7: This document is just a short introduction of the strongSwan **swanctl** command
8: which uses the modern [**vici**](src/libcharon/plugins/vici/README.md) *Versatile
9: IKE Configuration Interface*. The deprecated **ipsec** command using the legacy
10: **stroke** configuration interface is described [**here**](README_LEGACY.md).
11: For more detailed information consult the man pages and
12: [**our wiki**](https://wiki.strongswan.org).
13:
14:
15: ## Quickstart ##
16:
17: Certificates for users, hosts and gateways are issued by a fictitious
18: strongSwan CA. In our example scenarios the CA certificate `strongswanCert.pem`
19: must be present on all VPN endpoints in order to be able to authenticate the
20: peers. For your particular VPN application you can either use certificates from
21: any third-party CA or generate the needed private keys and certificates yourself
22: with the strongSwan **pki** tool, the use of which will be explained in one of
23: the sections following below.
24:
25:
26: ### Site-to-Site Case ###
27:
28: In this scenario two security gateways _moon_ and _sun_ will connect the
29: two subnets _moon-net_ and _sun-net_ with each other through a VPN tunnel
30: set up between the two gateways:
31:
32: 10.1.0.0/16 -- | 192.168.0.1 | === | 192.168.0.2 | -- 10.2.0.0/16
33: moon-net moon sun sun-net
34:
35: Configuration on gateway _moon_:
36:
37: /etc/swanctl/x509ca/strongswanCert.pem
38: /etc/swanctl/x509/moonCert.pem
39: /etc/swanctl/private/moonKey.pem
40:
41: /etc/swanctl/swanctl.conf:
42:
43: connections {
44: net-net {
45: remote_addrs = 192.168.0.2
46:
47: local {
48: auth = pubkey
49: certs = moonCert.pem
50: }
51: remote {
52: auth = pubkey
53: id = "C=CH, O=strongSwan, CN=sun.strongswan.org"
54: }
55: children {
56: net-net {
57: local_ts = 10.1.0.0/16
58: remote_ts = 10.2.0.0/16
59: start_action = trap
60: }
61: }
62: }
63: }
64:
65: Configuration on gateway _sun_:
66:
67: /etc/swanctl/x509ca/strongswanCert.pem
68: /etc/swanctl/x509/sunCert.pem
69: /etc/swanctl/private/sunKey.pem
70:
71: /etc/swanctl/swanctl.conf:
72:
73: connections {
74: net-net {
75: remote_addrs = 192.168.0.1
76:
77: local {
78: auth = pubkey
79: certs = sunCert.pem
80: }
81: remote {
82: auth = pubkey
83: id = "C=CH, O=strongSwan, CN=moon.strongswan.org"
84: }
85: children {
86: net-net {
87: local_ts = 10.2.0.0/16
88: remote_ts = 10.1.0.0/16
89: start_action = trap
90: }
91: }
92: }
93: }
94:
95: The local and remote identities used in this scenario are the
96: *subjectDistinguishedNames* contained in the end entity certificates.
97: The certificates and private keys are loaded into the **charon** daemon with
98: the command
99:
100: swanctl --load-creds
101:
102: whereas
103:
104: swanctl --load-conns
105:
106: loads the connections defined in `swanctl.conf`. With `start_action = trap` the
107: IPsec connection is automatically set up with the first plaintext payload IP
108: packet wanting to go through the tunnel.
109:
110: ### Host-to-Host Case ###
111:
112: This is a setup between two single hosts which don't have a subnet behind
113: them. Although IPsec transport mode would be sufficient for host-to-host
114: connections we will use the default IPsec tunnel mode.
115:
116: | 192.168.0.1 | === | 192.168.0.2 |
117: moon sun
118:
119: Configuration on host _moon_:
120:
121: /etc/swanctl/x509ca/strongswanCert.pem
122: /etc/swanctl/x509/moonCert.pem
123: /etc/swanctl/private/moonKey.pem
124:
125: /etc/swanctl/swanctl.conf:
126:
127: connections {
128: host-host {
129: remote_addrs = 192.168.0.2
130:
131: local {
132: auth=pubkey
133: certs = moonCert.pem
134: }
135: remote {
136: auth = pubkey
137: id = "C=CH, O=strongSwan, CN=sun.strongswan.org"
138: }
139: children {
140: net-net {
141: start_action = trap
142: }
143: }
144: }
145: }
146:
147: Configuration on host _sun_:
148:
149: /etc/swanctl/x509ca/strongswanCert.pem
150: /etc/swanctl/x509/sunCert.pem
151: /etc/swanctl/private/sunKey.pem
152:
153: /etc/swanctl/swanctl.conf:
154:
155: connections {
156: host-host {
157: remote_addrs = 192.168.0.1
158:
159: local {
160: auth = pubkey
161: certs = sunCert.pem
162: }
163: remote {
164: auth = pubkey
165: id = "C=CH, O=strongSwan, CN=moon.strongswan.org"
166: }
167: children {
168: host-host {
169: start_action = trap
170: }
171: }
172: }
173: }
174:
175:
176: ### Roadwarrior Case ###
177:
178: This is a very common case where a strongSwan gateway serves an arbitrary
179: number of remote VPN clients usually having dynamic IP addresses.
180:
181: 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
182: moon-net moon carol
183:
184: Configuration on gateway _moon_:
185:
186: /etc/swanctl/x509ca/strongswanCert.pem
187: /etc/swanctl/x509/moonCert.pem
188: /etc/swanctl/private/moonKey.pem
189:
190: /etc/swanctl/swanctl.conf:
191:
192: connections {
193: rw {
194: local {
195: auth = pubkey
196: certs = moonCert.pem
197: id = moon.strongswan.org
198: }
199: remote {
200: auth = pubkey
201: }
202: children {
203: net-net {
204: local_ts = 10.1.0.0/16
205: }
206: }
207: }
208: }
209:
210: Configuration on roadwarrior _carol_:
211:
212: /etc/swanctl/x509ca/strongswanCert.pem
213: /etc/swanctl/x509/carolCert.pem
214: /etc/swanctl/private/carolKey.pem
215:
216: /etc/swanctl/swanctl.conf:
217:
218: connections {
219: home {
220: remote_addrs = moon.strongswan.org
221:
222: local {
223: auth = pubkey
224: certs = carolCert.pem
225: id = carol@strongswan.org
226: }
227: remote {
228: auth = pubkey
229: id = moon.strongswan.org
230: }
231: children {
232: home {
233: local_ts = 10.1.0.0/16
234: start_action = start
235: }
236: }
237: }
238: }
239:
240: For `remote_addrs` the hostname `moon.strongswan.org` was chosen which will be
241: resolved by DNS at runtime into the corresponding IP destination address.
242: In this scenario the identity of the roadwarrior `carol` is the email address
243: `carol@strongswan.org` which must be included as a *subjectAlternativeName* in
244: the roadwarrior certificate `carolCert.pem`.
245:
246:
247: ### Roadwarrior Case with Virtual IP ###
248:
249: Roadwarriors usually have dynamic IP addresses assigned by the ISP they are
250: currently attached to. In order to simplify the routing from _moon-net_ back
251: to the remote access client _carol_ it would be desirable if the roadwarrior had
252: an inner IP address chosen from a pre-defined pool.
253:
254: 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x | -- 10.3.0.1
255: moon-net moon carol virtual IP
256:
257: In our example the virtual IP address is chosen from the address pool
258: `10.3.0.0/16` which can be configured by adding the section
259:
260: pools {
261: rw_pool {
262: addrs = 10.3.0.0/16
263: }
264: }
265:
266: to the gateway's `swanctl.conf` from where they are loaded into the **charon**
267: daemon using the command
268:
269: swanctl --load-pools
270:
271: To request an IP address from this pool a roadwarrior can use IKEv1 mode config
272: or IKEv2 configuration payloads. The configuration for both is the same
273:
274: vips = 0.0.0.0
275:
276: Configuration on gateway _moon_:
277:
278: /etc/swanctl/x509ca/strongswanCert.pem
279: /etc/swanctl/x509/moonCert.pem
280: /etc/swanctl/private/moonKey.pem
281:
282: /etc/swanctl/swanctl.conf:
283:
284: connections {
285: rw {
286: pools = rw_pool
287:
288: local {
289: auth = pubkey
290: certs = moonCert.pem
291: id = moon.strongswan.org
292: }
293: remote {
294: auth = pubkey
295: }
296: children {
297: net-net {
298: local_ts = 10.1.0.0/16
299: }
300: }
301: }
302: }
303:
304: pools {
305: rw_pool {
306: addrs = 10.30.0.0/16
307: }
308: }
309:
310: Configuration on roadwarrior _carol_:
311:
312: /etc/swanctl/x509ca/strongswanCert.pem
313: /etc/swanctl/x509/carolCert.pem
314: /etc/swanctl/private/carolKey.pem
315:
316: /etc/swanctl/swanctl.conf:
317:
318: connections {
319: home {
320: remote_addrs = moon.strongswan.org
321: vips = 0.0.0.0
322:
323: local {
324: auth = pubkey
325: certs = carolCert.pem
326: id = carol@strongswan.org
327: }
328: remote {
329: auth = pubkey
330: id = moon.strongswan.org
331: }
332: children {
333: home {
334: local_ts = 10.1.0.0/16
335: start_action = start
336: }
337: }
338: }
339: }
340:
341:
342: ### Roadwarrior Case with EAP Authentication ###
343:
344: This is a very common case where a strongSwan gateway serves an arbitrary
345: number of remote VPN clients which authenticate themselves via a password
346: based *Extended Authentication Protocol* as e.g. *EAP-MD5* or *EAP-MSCHAPv2*.
347:
348: 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
349: moon-net moon carol
350:
351: Configuration on gateway _moon_:
352:
353: /etc/swanctl/x509ca/strongswanCert.pem
354: /etc/swanctl/x509/moonCert.pem
355: /etc/swanctl/private/moonKey.pem
356:
357: /etc/swanctl/swanctl.conf:
358:
359: connections {
360: rw {
361: local {
362: auth = pubkey
363: certs = moonCert.pem
364: id = moon.strongswan.org
365: }
366: remote {
367: auth = eap-md5
368: }
369: children {
370: net-net {
371: local_ts = 10.1.0.0/16
372: }
373: }
374: send_certreq = no
375: }
376: }
377:
378: The `swanctl.conf` file additionally contains a `secrets` section defining all
379: client credentials
380:
381: secrets {
382: eap-carol {
383: id = carol@strongswan.org
384: secret = Ar3etTnp
385: }
386: eap-dave {
387: id = dave@strongswan.org
388: secret = W7R0g3do
389: }
390: }
391:
392: Configuration on roadwarrior _carol_:
393:
394: /etc/swanctl/x509ca/strongswanCert.pem
395:
396: /etc/swanctl/swanctl.conf:
397:
398: connections {
399: home {
400: remote_addrs = moon.strongswan.org
401:
402: local {
403: auth = eap
404: id = carol@strongswan.org
405: }
406: remote {
407: auth = pubkey
408: id = moon.strongswan.org
409: }
410: children {
411: home {
412: local_ts = 10.1.0.0/16
413: start_action = start
414: }
415: }
416: }
417: }
418:
419: secrets {
420: eap-carol {
421: id = carol@strongswan.org
422: secret = Ar3etTnp
423: }
424: }
425:
426:
427: ### Roadwarrior Case with EAP Identity ###
428:
429: Often a client EAP identity is exchanged via EAP which differs from the
430: external IKEv2 identity. In this example the IKEv2 identity defaults to
431: the IPv4 address of the client.
432:
433: 10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
434: moon-net moon carol
435:
436: Configuration on gateway _moon_:
437:
438: /etc/swanctl/x509ca/strongswanCert.pem
439: /etc/swanctl/x509/moonCert.pem
440: /etc/swanctl/private/moonKey.pem
441:
442: /etc/swanctl/swanctl.conf:
443:
444: connections {
445: rw {
446: local {
447: auth = pubkey
448: certs = moonCert.pem
449: id = moon.strongswan.org
450: }
451: remote {
452: auth = eap-md5
453: eap_id = %any
454: }
455: children {
456: net-net {
457: local_ts = 10.1.0.0/16
458: }
459: }
460: send_certreq = no
461: }
462: }
463:
464: secrets {
465: eap-carol {
466: id = carol
467: secret = Ar3etTnp
468: }
469: eap-dave {
470: id = dave
471: secret = W7R0g3do
472: }
473: }
474:
475: Configuration on roadwarrior _carol_:
476:
477: /etc/swanctl/x509ca/strongswanCert.pem
478:
479: /etc/swanctl/swanctl.conf:
480:
481: connections {
482: home {
483: remote_addrs = moon.strongswan.org
484:
485: local {
486: auth = eap
487: eap_id = carol
488: }
489: remote {
490: auth = pubkey
491: id = moon.strongswan.org
492: }
493: children {
494: home {
495: local_ts = 10.1.0.0/16
496: start_action = start
497: }
498: }
499: }
500: }
501:
502: secrets {
503: eap-carol {
504: id = carol
505: secret = Ar3etTnp
506: }
507: }
508:
509:
510: ## Generating Certificates and CRLs ##
511:
512: This section is not a full-blown tutorial on how to use the strongSwan **pki**
513: tool. It just lists a few points that are relevant if you want to generate your
514: own certificates and CRLs for use with strongSwan.
515:
516:
517: ### Generating a CA Certificate ###
518:
519: The pki statement
520:
521: pki --gen --type ed25519 --outform pem > strongswanKey.pem
522:
523: generates an elliptic Edwards-Curve key with a cryptographic strength of 128
524: bits. The corresponding public key is packed into a self-signed CA certificate
525: with a lifetime of 10 years (3652 days)
526:
527: pki --self --ca --lifetime 3652 --in strongswanKey.pem \
528: --dn "C=CH, O=strongSwan, CN=strongSwan Root CA" \
529: --outform pem > strongswanCert.pem
530:
531: which can be listed with the command
532:
533: pki --print --in strongswanCert.pem
534:
535: subject: "C=CH, O=strongSwan, CN=strongSwan Root CA"
536: issuer: "C=CH, O=strongSwan, CN=strongSwan Root CA"
537: validity: not before May 18 08:32:06 2017, ok
538: not after May 18 08:32:06 2027, ok (expires in 3651 days)
539: serial: 57:e0:6b:3a:9a:eb:c6:e0
540: flags: CA CRLSign self-signed
541: subjkeyId: 2b:95:14:5b:c3:22:87:de:d1:42:91:88:63:b3:d5:c1:92:7a:0f:5d
542: pubkey: ED25519 256 bits
543: keyid: a7:e1:6a:3f:e7:6f:08:9d:89:ec:23:92:a9:a1:14:3c:78:a8:7a:f7
544: subjkey: 2b:95:14:5b:c3:22:87:de:d1:42:91:88:63:b3:d5:c1:92:7a:0f:5d
545:
546: If you prefer the CA private key and X.509 certificate to be in binary DER format
547: then just omit the `--outform pem` option. The directory `/etc/swanctl/x509ca`
548: contains all required CA certificates either in binary DER or in Base64 PEM
549: format. Irrespective of the file suffix the correct format will be determined
550: by strongSwan automagically.
551:
552:
553: ### Generating a Host or User End Entity Certificate ###
554:
555: Again we are using the command
556:
557: pki --gen --type ed25519 --outform pem > moonKey.pem
558:
559: to generate an Ed25519 private key for the host `moon`. Alternatively you could
560: type
561:
562: pki --gen --type rsa --size 3072 > moonKey.der
563:
564: to generate a traditional 3072 bit RSA key and store it in binary DER format.
565: As an alternative a **TPM 2.0** *Trusted Platform Module* available on every
566: recent Intel platform could be used as a virtual smartcard to securely store an
567: RSA or ECDSA private key. For details, refer to the TPM 2.0
568: [HOWTO](https://wiki.strongswan.org/projects/strongswan/wiki/TpmPlugin).
569:
570: In a next step the command
571:
572: pki --req --type priv --in moonKey.pem \
573: --dn "C=CH, O=strongswan, CN=moon.strongswan.org" \
574: --san moon.strongswan.org --outform pem > moonReq.pem
575:
576: creates a PKCS#10 certificate request that has to be signed by the CA.
577: Through the [multiple] use of the `--san` parameter any number of desired
578: *subjectAlternativeNames* can be added to the request. These can be of the
579: form
580:
581: --san sun.strongswan.org # fully qualified host name
582: --san carol@strongswan.org # RFC822 user email address
583: --san 192.168.0.1 # IPv4 address
584: --san fec0::1 # IPv6 address
585:
586: Based on the certificate request the CA issues a signed end entity certificate
587: with the following command
588:
589: pki --issue --cacert strongswanCert.pem --cakey strongswanKey.pem \
590: --type pkcs10 --in moonReq.pem --serial 01 --lifetime 1826 \
591: --outform pem > moonCert.pem
592:
593: If the `--serial` parameter with a hexadecimal argument is omitted then a random
594: serial number is generated. Some third party VPN clients require that a VPN
595: gateway certificate contains the *TLS Server Authentication* Extended Key Usage
596: (EKU) flag which can be included with the following option
597:
598: --flag serverAuth
599:
600: If you want to use the dynamic CRL fetching feature described in one of the
601: following sections then you may include one or several *crlDistributionPoints*
602: in your end entity certificates using the `--crl` parameter
603:
604: --crl http://crl.strongswan.org/strongswan.crl
605: --crl "ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=strongSwan,c=CH?certificateRevocationList"
606:
607: The issued host certificate can be listed with
608:
609: pki --print --in moonCert.pem
610:
611: subject: "C=CH, O=strongSwan, CN=moon.strongswan.org"
612: issuer: "C=CH, O=strongSwan, CN=strongSwan Root CA"
613: validity: not before May 19 10:28:19 2017, ok
614: not after May 19 10:28:19 2022, ok (expires in 1825 days)
615: serial: 01
616: altNames: moon.strongswan.org
617: flags: serverAuth
618: CRL URIs: http://crl.strongswan.org/strongswan.crl
619: authkeyId: 2b:95:14:5b:c3:22:87:de:d1:42:91:88:63:b3:d5:c1:92:7a:0f:5d
620: subjkeyId: 60:9d:de:30:a6:ca:b9:8e:87:bb:33:23:61:19:18:b8:c4:7e:23:8f
621: pubkey: ED25519 256 bits
622: keyid: 39:1b:b3:c2:34:72:1a:01:08:40:ce:97:75:b8:be:ce:24:30:26:29
623: subjkey: 60:9d:de:30:a6:ca:b9:8e:87:bb:33:23:61:19:18:b8:c4:7e:23:8f
624:
625: Usually, a Windows, OSX, Android or iOS based VPN client needs its private key,
626: its host or user certificate and the CA certificate. The most convenient way
627: to load this information is to put everything into a PKCS#12 container:
628:
629: openssl pkcs12 -export -inkey carolKey.pem \
630: -in carolCert.pem -name "carol" \
631: -certfile strongswanCert.pem -caname "strongSwan Root CA" \
632: -out carolCert.p12
633:
634: The strongSwan **pki** tool currently is not able to create PKCS#12 containers
635: so that **openssl** must be used.
636:
637:
638: ### Generating a CRL ###
639:
640: An empty CRL that is signed by the CA can be generated with the command
641:
642: pki --signcrl --cacert strongswanCert.pem --cakey strongswanKey.pem \
643: --lifetime 30 > strongswan.crl
644:
645: If you omit the `--lifetime` option then the default value of 15 days is used.
646: CRLs can either be uploaded to a HTTP or LDAP server or put in binary DER or
647: Base64 PEM format into the `/etc/swanctl/x509crl` directory from where they are
648: loaded into the **charon** daemon with the command
649:
650: swanctl --load-creds
651:
652:
653: ### Revoking a Certificate ###
654:
655: A specific end entity certificate is revoked with the command
656:
657: pki --signcrl --cacert strongswanCert.pem --cakey strongswanKey.pem \
658: --lifetime 30 --lastcrl strongswan.crl \
659: --reason key-compromise --cert moonCert.pem > new.crl
660:
661: Instead of the certificate file (in our example moonCert.pem), the serial number
662: of the certificate to be revoked can be indicated using the `--serial`
663: parameter. The `pki --signcrl --help` command documents all possible revocation
664: reasons but the `--reason` parameter can also be omitted. The content of the new
665: CRL file can be listed with the command
666:
667: pki --print --type crl --in new.crl
668:
669: issuer: "C=CH, O=strongSwan, CN=strongSwan Root CA"
670: update: this on May 19 11:13:01 2017, ok
671: next on Jun 18 11:13:01 2017, ok (expires in 29 days)
672: serial: 02
673: authKeyId: 2b:95:14:5b:c3:22:87:de:d1:42:91:88:63:b3:d5:c1:92:7a:0f:5d
674: 1 revoked certificate:
675: 01: May 19 11:13:01 2017, key compromise
676:
677:
678: ### Local Caching of CRLs ###
679:
680: The `strongswan.conf` option
681:
682: charon {
683: cache_crls = yes
684: }
685:
686: activates the local caching of CRLs that were dynamically fetched from an
687: HTTP or LDAP server. Cached copies are stored in `/etc/swanctl/x509crl` using a
688: unique filename formed from the issuer's *subjectKeyIdentifier* and the
689: suffix `.crl`.
690:
691: With the cached copy the CRL is immediately available after startup. When the
692: local copy has become stale, an updated CRL is automatically fetched from one of
693: the defined CRL distribution points during the next IKEv2 authentication.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan