Modern operating systems (such as Windows 7 and newer) support the IKEv2 standard. Internet Key Exchange (IKE or IKEv2) is the protocol used to set up a Security Association (SA) in the IPsec protocol suite. Compared to IKE version 1, IKEv2 contains <ahref="https://en.wikipedia.org/wiki/Internet_Key_Exchange#Improvements_with_IKEv2"target="_blank">improvements</a> such as Standard Mobility support through MOBIKE, and improved reliability.
Libreswan can authenticate IKEv2 clients on the basis of X.509 Machine Certificates using RSA signatures. This method does not require an IPsec PSK, username or password. It can be used with:
After following this guide, you will be able to connect to the VPN using IKEv2 in addition to the existing [IPsec/L2TP](clients.md) and [IPsec/XAuth ("Cisco IPsec")](clients-xauth.md) modes.
**Important:** Before continuing, you should have successfully <ahref="https://github.com/hwdsl2/setup-ipsec-vpn"target="_blank">set up your own VPN server</a>, and (optional but recommended) <ahref="../README.md#upgrade-libreswan"target="_blank">updated Libreswan</a>. **Docker users, see <a href="https://github.com/hwdsl2/docker-ipsec-vpn-server/blob/master/README.md#configure-and-use-ikev2-vpn" target="_blank">here</a>**.
The <ahref="../extras/ikev2setup.sh"target="_blank">script</a> must be run using `bash`, not `sh`. The command above runs the helper script in auto mode, using default options. Remove the `--auto` parameter if you want to customize IKEv2 setup options. When finished, continue to [configure IKEv2 VPN clients](#configure-ikev2-vpn-clients).
When running IKEv2 setup in auto mode, advanced users can optionally specify a DNS name to be used as the VPN server's address. The DNS name must be a fully qualified domain name (FQDN). Example:
By default, IKEv2 clients are set to use <ahref="https://developers.google.com/speed/public-dns/"target="_blank">Google Public DNS</a> when the VPN is active. When running IKEv2 setup in auto mode, you may optionally specify custom DNS server(s). Example:
**Note:** The password for client configuration files can be found in the output of the IKEv2 helper script. If you want to add or export IKEv2 client(s), just run the [helper script](#using-helper-scripts) again. Use option `-h` to show usage information.
1. Securely transfer the generated `.p12` file to your computer, then import it into the "Computer account" certificate store. To import the `.p12` file, run the following from an <ahref="http://www.winhelponline.com/blog/open-elevated-command-prompt-windows/"target="_blank">elevated command prompt</a>:
Alternatively, you can manually import the `.p12` file. Click <ahref="https://wiki.strongswan.org/projects/strongswan/wiki/Win7Certs"target="_blank">here</a> for instructions. Make sure that the client cert is placed in "Personal -> Certificates", and the CA cert is placed in "Trusted Root Certification Authorities -> Certificates".
**Note:** Ubuntu 18.04 users may encounter the error "The password you entered is incorrect" when trying to import the `.p12` file. See [Troubleshooting](#troubleshooting).
1. On the Windows computer, add a new IKEv2 VPN connection. For Windows 8.x and 10, it is recommended to create the VPN connection using the following commands from a command prompt, for improved security and performance. Windows 7 does not support these commands, you may manually create the VPN connection (see below).
Alternatively, you can manually create the VPN connection. Click <ahref="https://wiki.strongswan.org/projects/strongswan/wiki/Win7Config"target="_blank">here</a> for instructions. If you specified the server's DNS name (instead of its IP address) during IKEv2 setup, you must enter the DNS name in the **Internet address** field.
1. Enable stronger ciphers for IKEv2 with a one-time registry change. This is optional, but recommended. Download and import the `.reg` file below, or run the following from an elevated command prompt. Read more <ahref="https://wiki.strongswan.org/projects/strongswan/wiki/WindowsClients#AES-256-CBC-and-MODP2048"target="_blank">here</a>.
To connect to the VPN: Click on the wireless/network icon in your system tray, select the new VPN entry, and click **Connect**. Once successfully connected, you can verify that your traffic is being routed properly by <ahref="https://www.google.com/search?q=my+ip"target="_blank">looking up your IP address on Google</a>. It should say "Your public IP address is `Your VPN Server IP`".
First, securely transfer the generated `.mobileconfig` file to your Mac, then double-click and follow the prompts to import as a macOS profile. When finished, check to make sure "IKEv2 VPN" is listed under System Preferences -> Profiles.
1. Open System Preferences and go to the Network section.
1. Select the VPN connection with `Your VPN Server IP` (or DNS name).
1. Check the **Show VPN status in menu bar** checkbox.
1. Click **Connect**.
(Optional feature) You can choose to enable <ahref="https://developer.apple.com/documentation/networkextension/personal_vpn/vpn_on_demand_rules"target="_blank">VPN On Demand</a>. This is an "always-on" feature that can automatically connect to the VPN while on Wi-Fi. To enable, check the **Connect on demand** checkbox for the VPN connection, and click **Apply**.
First, securely transfer the generated `.p12` file to your Mac, then double-click to import into the **login** keychain in **Keychain Access**. Next, double-click on the imported `IKEv2 VPN CA` certificate, expand **Trust** and select **Always Trust** from the **IP Security (IPsec)** drop-down menu. Close the dialog using the red "X" on the top-left corner. When prompted, use Touch ID or enter your password and click "Update Settings".
When finished, check to make sure both the new client certificate and `IKEv2 VPN CA` are listed under the **Certificates** category of **login** keychain.
1. Open System Preferences and go to the Network section.
1. Click the **+** button in the lower-left corner of the window.
1. Select **VPN** from the **Interface** drop-down menu.
1. Select **IKEv2** from the **VPN Type** drop-down menu.
1. Enter anything you like for the **Service Name**.
1. Enter `Your VPN Server IP` (or DNS name) for the **Server Address**.
**Note:** If you specified the server's DNS name (instead of its IP address) during IKEv2 setup, you must enter the DNS name in the **Server Address** and **Remote ID** fields.
Once successfully connected, you can verify that your traffic is being routed properly by <ahref="https://www.google.com/search?q=my+ip"target="_blank">looking up your IP address on Google</a>. It should say "Your public IP address is `Your VPN Server IP`".
First, securely transfer the generated `.mobileconfig` file to your iOS device, then import it as an iOS profile. To transfer the file, you may use:
1. AirDrop, or
1. Upload to your device using "File Sharing" in iTunes, then open the "Files" app on your iOS device, move the uploaded file to the "On My iPhone" folder. After that, tap the file and go to "Settings" to import, or
1. Host the file on a secure website of yours, then download and import it in Mobile Safari.
1. Select the VPN connection with `Your VPN Server IP` (or DNS name).
1. Slide the **VPN** switch ON.
(Optional feature) You can choose to enable <ahref="https://developer.apple.com/documentation/networkextension/personal_vpn/vpn_on_demand_rules"target="_blank">VPN On Demand</a>. This is an "always-on" feature that can automatically connect to the VPN while on Wi-Fi. To enable, tap the "i" icon on the right of the VPN connection, and enable **Connect On Demand**.
First, securely transfer the generated `ikev2vpnca.cer` and `.p12` files to your iOS device, then import them one by one as iOS profiles. To transfer the files, you may use:
1. Upload to your device using "File Sharing" in iTunes, then open the "Files" app on your iOS device, move the uploaded files to the "On My iPhone" folder. After that, tap each file and go to "Settings" to import, or
1. Tap **Server** and enter `Your VPN Server IP` (or DNS name).
**Note:** If you specified the server's DNS name (instead of its IP address) during IKEv2 setup, you must enter the DNS name in the **Server** and **Remote ID** fields.
Once successfully connected, you can verify that your traffic is being routed properly by <ahref="https://www.google.com/search?q=my+ip"target="_blank">looking up your IP address on Google</a>. It should say "Your public IP address is `Your VPN Server IP`".
If your device runs Android 6.0 or older, click here for additional instructions.
</summary>
If your device runs Android 6.0 (Marshmallow) or older, in order to connect using the strongSwan VPN client, you must make the following change on the VPN server: Edit `/etc/ipsec.d/ikev2.conf` on the server. Append `authby=rsa-sha1` to the end of the `conn ikev2-cp` section, indented by two spaces. Save the file and run `service ipsec restart`.
(Optional feature) You can choose to enable the "Always-on VPN" feature on Android. Launch the **Settings** app, go to Network & internet -> Advanced -> VPN, click the gear icon on the right of "strongSwan VPN Client", then enable the **Always-on VPN** and **Block connections without VPN** options.
Once successfully connected, you can verify that your traffic is being routed properly by <ahref="https://www.google.com/search?q=my+ip"target="_blank">looking up your IP address on Google</a>. It should say "Your public IP address is `Your VPN Server IP`".
Before configuring Linux VPN clients, you must make the following change on the VPN server: Edit `/etc/ipsec.d/ikev2.conf` on the server. Append `authby=rsa-sha1` to the end of the `conn ikev2-cp` section, indented by two spaces. Save the file and run `service ipsec restart`.
To configure your Linux computer to connect to IKEv2 as a VPN client, first install the strongSwan plugin for NetworkManager:
Next, securely transfer the generated `.p12` file from the VPN server to your Linux computer. After that, extract the CA certificate, client certificate and private key. Replace `vpnclient.p12` in the example below with the name of your `.p12` file.
```bash
# Example: Extract CA certificate, client certificate and private key.
# You may delete the .p12 file when finished.
# Note: You will need to enter the import password, which can be found
You can then set up and enable the VPN connection:
1. Go to Settings -> Network -> VPN. Click the **+** button.
1. Select **IPsec/IKEv2 (strongswan)**.
1. Enter anything you like in the **Name** field.
1. In the **Gateway (Server)** section, enter `Your VPN Server IP` (or DNS name) for the **Address**.
1. Select the `ikev2vpnca.cer` file for the **Certificate**.
1. In the **Client** section, select **Certificate(/private key)** in the **Authentication** drop-down menu.
1. Select **Certificate/private key** in the **Certificate** drop-down menu (if exists).
1. Select the `vpnclient.cer` file for the **Certificate (file)**.
1. Select the `vpnclient.key` file for the **Private key**.
1. In the **Options** section, check the **Request an inner IP address** checkbox.
1. In the **Cipher proposals (Algorithms)** section, check the **Enable custom proposals** checkbox.
1. Leave the **IKE** field blank.
1. Enter `aes128gcm16` in the **ESP** field.
1. Click **Add** to save the VPN connection information.
1. Turn the **VPN** switch ON.
Once successfully connected, you can verify that your traffic is being routed properly by <ahref="https://www.google.com/search?q=my+ip"target="_blank">looking up your IP address on Google</a>. It should say "Your public IP address is `Your VPN Server IP`".
If you get an error when trying to connect, see [Troubleshooting](#troubleshooting).
If you want to list the names of existing IKEv2 clients, run the [helper script](#using-helper-scripts) with the `--listclients` option. Use option `-h` to show usage information.
To generate certificates for additional IKEv2 clients, just run the [helper script](#using-helper-scripts) again. Or you may refer to step 4 in [this section](#manually-set-up-ikev2-on-the-vpn-server).
By default, the [IKEv2 helper script](#using-helper-scripts) exports client configuration after running. If later you want to export configuration for an existing client, run the helper script again and select the appropriate option.
**Important:** Deleting a client certificate from the IPsec database **WILL NOT** prevent VPN client(s) from connecting using that certificate! For this use case, you **MUST** [revoke the client certificate](#revoke-a-client-certificate) instead of deleting it.
<details>
<summary>
First, read the important note above. Then click here for instructions.
**Important:** Please first read the important note above. If you still want to delete a certificate, refer to the steps below. This action **cannot be undone**!
1. Delete the client certificate and private key. Replace "Nickname" below with the nickname of the client certificate you want to delete, e.g. `vpnclient`.
In certain circumstances, you may need to revoke a previously generated VPN client certificate. This can be done using `crlutil`. See example steps below, commands must be run as `root`.
1. Check the database, and identify the nickname of the client certificate you want to revoke.
```bash
certutil -L -d sql:/etc/ipsec.d
```
```
Certificate Nickname Trust Attributes
SSL,S/MIME,JAR/XPI
IKEv2 VPN CA CTu,u,u
($PUBLIC_IP) u,u,u
vpnclient-to-revoke u,u,u
```
In this example, we will revoke the certificate with nickname `vpnclient-to-revoke`, issued by `IKEv2 VPN CA`.
1. Find the serial number of this client certificate.
Signature Algorithm: PKCS #1 SHA-256 With RSA Encryption
Issuer: "O=IKEv2 VPN,CN=IKEv2 VPN CA"
This Update: Sat Jun 06 22:00:00 2020
CRL Extensions:
```
1. Add the client certificate you want to revoke to the CRL. Here we specify the certificate's serial number in decimal, and the revocation time in GeneralizedTime format (YYYYMMDDhhmmssZ) in UTC.
Signature Algorithm: PKCS #1 SHA-256 With RSA Encryption
Issuer: "O=IKEv2 VPN,CN=IKEv2 VPN CA"
This Update: Sat Jun 06 22:02:00 2020
Entry 1 (0x1):
Serial Number:
00:cd:69:ff:74
Revocation Date: Sat Jun 06 22:01:00 2020
CRL Extensions:
```
**Note:** If you want to remove a certificate from the CRL, replace `addcert 3446275956 20200606220100Z` above with `rmcert 3446275956`. For other `crlutil` usage, read <ahref="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/tools/NSS_Tools_crlutil"target="_blank">here</a>.
1. Finally, let Libreswan re-read the updated CRL.
As an alternative to using the [helper script](#using-helper-scripts), advanced users can manually set up IKEv2. Before continuing, it is recommended to <ahref="../README.md#upgrade-libreswan"target="_blank">update Libreswan</a> to the latest version.
The following example shows how to manually configure IKEv2 with Libreswan. Commands below must be run as `root`.
**Note:** If you specified the server's DNS name (instead of its IP address) in step 1 above, you must replace `leftid=$PUBLIC_IP` in the command below with `leftid=@$PUBLIC_IP`.
**Note:** The <ahref="https://wiki.strongswan.org/projects/strongswan/wiki/MobIke"target="_blank">MOBIKE</a> IKEv2 extension allows VPN clients to change network attachment points, e.g. switch between mobile data and Wi-Fi and keep the IPsec tunnel up on the new IP. If your server (or Docker host) is **NOT** running Ubuntu Linux, and you wish to enable MOBIKE support, replace `mobike=no` with `mobike=yes` in the command above. **DO NOT** enable this option on Ubuntu systems or Raspberry Pis.
**Note:** If you specified the server's DNS name (instead of its IP address) in step 1 above, you must replace `--extSAN "ip:$PUBLIC_IP,dns:$PUBLIC_IP"` in the command below with `--extSAN "dns:$PUBLIC_IP"`.
**Note:** You may repeat this step to generate certificates for additional VPN clients, but make sure to replace every `vpnclient` with `vpnclient2`, etc. To connect multiple VPN clients simultaneously, you must generate a unique certificate for each.
**Note:** To display a certificate, use `certutil -L -d sql:/etc/ipsec.d -n "Nickname"`. To revoke a client certificate, follow [these steps](#revoke-a-client-certificate). For other `certutil` usage, read <ahref="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/tools/NSS_Tools_certutil"target="_blank">here</a>.
Before continuing, you **must** restart the IPsec service. The IKEv2 setup on the VPN server is now complete. Follow instructions to [configure VPN clients](#configure-ikev2-vpn-clients).
If you forgot the password for client config files, you may [export configuration for the IKEv2 client](#export-configuration-for-an-existing-client) again.
Ubuntu 18.04 users may encounter the error "The password you entered is incorrect" when trying to import the generated `.p12` file into Windows. This is due to a bug in `NSS`. Read more <ahref="https://github.com/hwdsl2/setup-ipsec-vpn/issues/414#issuecomment-460495258"target="_blank">here</a>.
**Note:** This workaround should only be used on Ubuntu 18.04 systems running on the `x86_64` architecture. As of 2021-01-21, the IKEv2 helper script was updated to automatically apply this workaround.
First, install newer versions of `libnss3` related packages:
If the IKEv2 connection disconnects automatically after one hour (60 minutes), apply this fix: Edit `/etc/ipsec.d/ikev2.conf` on the VPN server (or `/etc/ipsec.conf` if it does not exist), append these lines to the end of section `conn ikev2-cp`, indented by two spaces:
```
ikelifetime=24h
salifetime=24h
```
Save the file and run `service ipsec restart`. As of 2021-01-20, the IKEv2 helper script was updated to include this fix.
### Unable to connect multiple IKEv2 clients
To connect multiple IKEv2 clients simultaneously, you must [generate a unique certificate](#add-a-client-certificate) for each.
If you are unable to connect multiple IKEv2 clients simultaneously from behind the same NAT (e.g. home router), apply this fix: Edit `/etc/ipsec.d/ikev2.conf` on the VPN server, find the line `leftid=@<your_server_ip>` and remove the `@`, i.e. replace it with `leftid=<your_server_ip>`. Save the file and run `service ipsec restart`. Do not apply this fix if `leftid` is a DNS name, which is not affected. As of 2021-02-01, the IKEv2 helper script was updated to include this fix.
### Other known issues
1. The built-in VPN client in Windows may not support IKEv2 fragmentation (this feature <ahref="https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-ikee/74df968a-7125-431d-9c98-4ea929e548dc"target="_blank">requires</a> Windows 10 v1803 or newer). On some networks, this can cause the connection to fail or have other issues. You may instead try the <ahref="clients.md"target="_blank">IPsec/L2TP</a> or <ahref="clients-xauth.md"target="_blank">IPsec/XAuth</a> mode.
1. If using the strongSwan Android VPN client, you must <ahref="../README.md#upgrade-libreswan"target="_blank">update Libreswan</a> on your server to version 3.26 or above.
If you want to remove IKEv2 from the VPN server, but keep the [IPsec/L2TP](clients.md) and [IPsec/XAuth ("Cisco IPsec")](clients-xauth.md) modes (if installed), run the [helper script](#using-helper-scripts) again and select the "Remove IKEv2" option. Note that this will delete all IKEv2 configuration including certificates and keys, and **cannot be undone**!
To manually remove IKEv2 from the VPN server, but keep the [IPsec/L2TP](clients.md) and [IPsec/XAuth ("Cisco IPsec")](clients-xauth.md) modes, follow these steps. Commands must be run as `root`. Note that this will delete all IKEv2 configuration including certificates and keys, and **cannot be undone**!
**Note:** If you used an older version (before 2020-05-31) of the IKEv2 helper script or instructions, file `/etc/ipsec.d/ikev2.conf` may not exist. In this case, please instead remove the `conn ikev2-cp` section from file `/etc/ipsec.conf`.
1. Delete certificates and keys. Replace "Nickname" below with each certificate's nickname. Repeat these commands for each certificate. When finished, list certificates in the IPsec database again, and confirm that the list is empty.
This work is licensed under the <ahref="http://creativecommons.org/licenses/by-sa/3.0/"target="_blank">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>
Attribution required: please include my name in any derivative and let me know how you have improved it!
