README.md

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